# Truth And Deception Environment Documentation

## Overview

**Taboo** is a classic two-player word game where one player, the **Clue Giver**, provides verbal clues to help the other player, the **Guesser**, identify a secret word without using a set of forbidden "taboo" words. The game emphasizes creativity and effective communication under constraints.



## Action Space

- **Format:**
  - **Clue Giver:** Any string representing the clue, **excluding** the taboo words and the word to guess.
  - **Guesser:** Must provide their guess within squared brackets. For example: `[apple]`.

- **Examples:**
  - **Clue Giver:** `"It's something you might eat for breakfast."`
  - **Guesser:** `"[toast]"`

- **Notes:**
  - Clue Givers must avoid using any taboo words or the word to guess in their clues.
  - Guessers must format their guesses within squared brackets to be recognized by the environment.


## Observation Space

### Observations

Each player receives a series of messages exchanged during the game, along with their specific roles and objectives.


**Reset Observation:**
On reset, each player receives a prompt tailored to their role. For example:

- **Clue Giver (Player 0):**
```plaintext
[Game]: You are Player 0, the Clue Giver in the Taboo game.
The word to guess is 'apple'.
Taboo words: fruit, red, pie.
Your goal is to provide clues to the Guesser without using the taboo words or the word to guess.
You have 30 turns to help the Guesser guess the word.
On your turn, simply type your clue.
```

- **Guesser (Player 1):**
```plaintext
[Game]: You are Player 1, the Guesser in the Taboo game.
Your goal is to guess the secret word based on the clues provided by the Clue Giver.
You have 30 turns to guess the word.
On your turn, type your guess within squared brackets. For example: '[apple]'.
```


**Step Observation:**
After each step, players receive the latest action taken by their opponent. For example:
```plaintext
[Clue Giver (Player 0)]: It's something you might eat for breakfast.
[Guesser (Player 1)]: [toast]
```


## Gameplay
- **Players**: 2
- **Roles**: Player 0 plays as the Clue Giver, Player 1 plays as the Guesser.
- **Turns**: Players alternate turns based on their roles.
- **Target Word**: The Clue Giver is assigned a secret word along with a list of taboo words that cannot be used in clues.
- **Objective**:
    - **Clue Giver**: Provide effective clues to help the Guesser identify the secret word without using any taboo words or the word itself.
    - **Guesser**: Deduce the secret word based on the clues provided by the Clue Giver by making guesses within squared brackets.
- **Turn Limit:** The game can be configured with a maximum number of turns. If the Guesser does not correctly guess the word within this limit, the game ends.

## Key Rules
1. Clue Giver's Rules:
    - Must not use any of the taboo words or the word to guess in their clues.
    - Clues should be clear enough to help the Guesser but subtle to avoid using forbidden terms.

2. Guesser's Rules:
    - Must format their guesses within squared brackets (e.g., `[apple]`).
    - Only guesses within the correct format are considered valid.

3. Winning Conditions:
    - **Win:** Both players win if the word is guessed correctly.
    - **Draw:** The game ends in a draw if the turn limit is reached.
    - **Invalid Move:** If a player makes an invalid move they lose with a -1 reward.

4. Game Termination:
    - The game ends immediately upon a win or an invalid move.
    - If the turn limit is reached without a correct guess, the game ends in a draw.

## Rewards

| Outcome          | Reward for Player | Reward for Opponent |
|------------------|:-----------------:|:-------------------:|
| **Win**          | `+1`              | `-1`                |
| **Draw**         |  `0`              |  `0`                |
| **Invalid Move** | `-1`              |  `0`                |


## Parameters

- `categories` (`List[str]`):
    - **Description**: Specifies the categories from which words are selected (e.g., [`"animals"`]).
    - **Impact**: Determines the pool of words and taboo words used in the game.

- `max_turns` (`int`):
    - **Description**: Sets the maximum number of turns allowed before the game ends in a draw.
    - **Impact**: Limits the duration of the game, encouraging timely clues and guesses.

- `data_path` (`str`):
    - **Description**: Path to the JSON file containing the list of words and their associated taboo words.
    - **Impact**: Allows customization of the word pool used in the game.



## Variants

| Env-id                     | max_turns  | categories                                                                 |
|----------------------------|:----------:|:--------------------------------------------------------------------------:|
| `Taboo-v0`                 | `6`        | `things`                                                                   |
| `Taboo-v0-animals`         | `6`        | `animals`                                                                  |
| `Taboo-v0-cars`            | `6`        | `cars`                                                                     |
| `Taboo-v0-city/country`    | `6`        | `city/country`                                                             |
| `Taboo-v0-food`            | `6`        | `food`                                                                     |
| `Taboo-v0-literature`      | `6`        | `literature`                                                               |
| `Taboo-v0-people`          | `6`        | `people`                                                                   |
| `Taboo-v0-tv`              | `6`        | `tv`                                                                       |
| `Taboo-v0-long`            | `24`       | `things`                                                                   |
| `Taboo-v0-full`            | `6`        | `things`,`animals`,`cars`,`city/country`,`food`,`literature`,`people`,`tv` |



## Example Usage

```python
import textarena as ta

# Initialize the environment
env = ta.make(env_id="Taboo-v0")

# Wrap the environment for easier observation handling
env = ta.wrappers.LLMObservationWrapper(env=env)

# Initialize agents
agent0 = ta.default_agents.GPTAgent(model="gpt-4o")
agent1 = ta.default_agents.GPTAgent(model="gpt-4o-mini")


# Reset the environment to start a new game
observations = env.reset()

# Game loop
done = False
while not done:
    for player_id, agent in enumerate([agent0, agent1]):
        # Get the current observation for the player
        obs = observations[player_id]

        # Agent decides on an action based on the observation
        action = agent(obs)

        # Execute the action in the environment
        (
            observations, 
            rewards, 
            truncated, 
            terminated, 
            info
        ) = env.step(player_id, action)

        # Check if the game has ended
        done = terminated or truncated

        # Optionally render the environment to see the current state
        # env.render()

        if done:
            break
# print the game results
for player_id, agent in enumerate([agent0, agent1]):
    print(f"{agent.agent_identifier}: {rewards[player_id]}")
print(f"Reason: {info['reason']}")
```

## Troubleshooting

- **Clue Giver Uses a Taboo Word:**
    - **Issue:** The Clue Giver includes a taboo word or the word to guess in their clue.
    - **Solution:** Ensure that the Clue Giver carefully avoids using any taboo words or the word to guess in their clues.

- **Guesser Fails to Format Guess Correctly:**
    - **Issue:** The Guesser provides a guess without using squared brackets (e.g.,`apple` instead of `[apple]`).
    - **Solution:** Instruct the Guesser to always format their guesses within squared brackets, such as `[apple]`.


## Version History
- **v0**
  - Initial release 



### Contact
If you have questions or face issues with this specific environment, please reach out directly to Guertlerlo@cfar.a-star.edu.sg