> ## Documentation Index
> Fetch the complete documentation index at: https://nonkit.rlaneth.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Game Commands

> Control battles, events, items, gold, time, and audio

Game commands affect gameplay state, trigger systems, and control the game world.

<Warning>
  These function signatures are based on analysis of the game's files. Some behaviors and parameter descriptions are inferred and may not be fully accurate. Furthermore, the game is in Early Access and may change over time.
</Warning>

## Battle Commands

### start\_battle

Initiates a battle encounter.

```yarn theme={null}
<<start_battle 1001>>
```

| Parameter | Type | Description             |
| --------- | ---- | ----------------------- |
| `id`      | int  | Battle configuration ID |

### start\_predefined\_battle

Starts a predefined battle configuration.

```yarn theme={null}
<<start_predefined_battle 1001>>
```

| Parameter | Type | Description          |
| --------- | ---- | -------------------- |
| `id`      | int  | Predefined battle ID |

### start\_level

Starts a game level.

```yarn theme={null}
<<start_level 1>>
<<start_level 1 true>>
```

| Parameter | Type | Default  | Description                  |
| --------- | ---- | -------- | ---------------------------- |
| `id`      | int  | required | Level ID                     |
| `isPlot`  | bool | `true`   | Whether this is a plot level |

### pause\_battle / resume\_battle

Pauses or resumes the current battle.

```yarn theme={null}
<<pause_battle>>
<<resume_battle>>
```

## Event Commands

### add\_event\_trigger

Adds a trigger for an event.

```yarn theme={null}
<<add_event_trigger "NodeName" "EventName">>
<<add_event_trigger "NodeName" "EventName" "arg1" "arg2">>
```

| Parameter   | Type   | Default  | Description       |
| ----------- | ------ | -------- | ----------------- |
| `node`      | string | required | Node to trigger   |
| `eventName` | string | required | Event identifier  |
| `arg1`      | string | `""`     | Optional argument |
| `arg2`      | string | `""`     | Optional argument |

### event\_end

Ends the current event and returns control to gameplay.

```yarn theme={null}
<<event_end>>
```

<Note>
  Always call `event_end` at the end of your dialogue to properly close the event.
</Note>

### event\_cancel

Cancels the current event without completing it.

```yarn theme={null}
<<event_cancel>>
```

### clear\_all\_event

Clears all active events.

```yarn theme={null}
<<clear_all_event>>
```

## Character Management

### add\_character

Adds a character to the player's party.

```yarn theme={null}
<<add_character 1003>>
```

| Parameter | Type | Description  |
| --------- | ---- | ------------ |
| `id`      | int  | Character ID |

**Known Character IDs:**

| ID   | Character    |
| ---- | ------------ |
| 1000 | Protagonist  |
| 1001 | Lilith (莉莉丝) |
| 1002 | Karen (卡莲)   |
| 1003 | Sartre (夏特露) |
| 1004 | Fouco (弗子)   |
| 1005 | Green (格林)   |

### remove\_character

Removes a character from the party.

```yarn theme={null}
<<remove_character 1003>>
```

| Parameter | Type | Description  |
| --------- | ---- | ------------ |
| `id`      | int  | Character ID |

### heal\_charactor

Heals a character by a percentage.

```yarn theme={null}
<<heal_charactor 1002 0.5>>
```

| Parameter | Type  | Description                 |
| --------- | ----- | --------------------------- |
| `id`      | int   | Character ID                |
| `p`       | float | Heal percentage (0.5 = 50%) |

<Note>
  Note the spelling: `heal_charactor` (not "character").
</Note>

### injure\_charactor

Damages a character by a percentage.

```yarn theme={null}
<<injure_charactor 1002 0.25>>
```

| Parameter | Type  | Description       |
| --------- | ----- | ----------------- |
| `id`      | int   | Character ID      |
| `p`       | float | Damage percentage |

## Items and Currency

### change\_item

Adds or removes items from inventory.

```yarn theme={null}
<<change_item 2007 9 true>>
<<change_item 2008 -1 true>>
<<change_item 1001 2 false>>
```

| Parameter | Type | Default  | Description                   |
| --------- | ---- | -------- | ----------------------------- |
| `id`      | int  | required | Item ID                       |
| `num`     | int  | required | Quantity (negative to remove) |
| `show`    | bool | `true`   | Show notification             |

### set\_item

Sets item quantity directly.

```yarn theme={null}
<<set_item 2007 5>>
```

| Parameter | Type | Description  |
| --------- | ---- | ------------ |
| `id`      | int  | Item ID      |
| `num`     | int  | New quantity |

### change\_gold

Modifies the player's gold.

```yarn theme={null}
<<change_gold 100>>
<<change_gold -50>>
```

| Parameter | Type | Description                        |
| --------- | ---- | ---------------------------------- |
| `value`   | int  | Gold change (positive or negative) |

### change\_affection

Changes affection level with a character.

```yarn theme={null}
<<change_affection 1001 10 true>>
<<change_affection 1002 -10 true>>
```

| Parameter | Type | Default  | Description       |
| --------- | ---- | -------- | ----------------- |
| `id`      | int  | required | Character ID      |
| `value`   | int  | required | Affection change  |
| `show`    | bool | `true`   | Show notification |

### change\_reputation

Changes player reputation.

```yarn theme={null}
<<change_reputation 15 true>>
<<change_reputation -7 true>>
```

| Parameter | Type | Default  | Description       |
| --------- | ---- | -------- | ----------------- |
| `value`   | int  | required | Reputation change |
| `show`    | bool | `true`   | Show notification |

## Attributes

### change\_attribute

Changes a player attribute.

```yarn theme={null}
<<change_attribute Strength 5 true>>
<<change_attribute Willpower -3 true>>
```

| Parameter | Type   | Default  | Description       |
| --------- | ------ | -------- | ----------------- |
| `name`    | string | required | Attribute name    |
| `value`   | int    | required | Change amount     |
| `show`    | bool   | `true`   | Show notification |

### increase\_attribute

Increases an attribute (alias for positive change).

```yarn theme={null}
<<increase_attribute DEX 2 true>>
```

| Parameter | Type   | Default  | Description       |
| --------- | ------ | -------- | ----------------- |
| `name`    | string | required | Attribute name    |
| `value`   | int    | required | Increase amount   |
| `show`    | bool   | `true`   | Show notification |

### add\_exp

Adds experience to a character.

```yarn theme={null}
<<add_exp 1002 100>>
```

| Parameter     | Type | Description       |
| ------------- | ---- | ----------------- |
| `characterID` | int  | Character ID      |
| `value`       | int  | Experience points |

## Time Management

### next\_day

Advances to the next day.

```yarn theme={null}
<<next_day>>
```

### next\_period

Advances to the next time period.

```yarn theme={null}
<<next_period>>
<<next_period true>>
```

| Parameter               | Type | Default | Description         |
| ----------------------- | ---- | ------- | ------------------- |
| `skipEventTriggerCheck` | bool | `false` | Skip event triggers |

### jump\_to\_period

Jumps to a specific day and period.

```yarn theme={null}
<<jump_to_period 5 "Morning">>
```

| Parameter | Type   | Description |
| --------- | ------ | ----------- |
| `day`     | int    | Target day  |
| `period`  | string | Period name |

## UI Commands

### open\_view

Opens a game UI view.

```yarn theme={null}
<<open_view GuildView>>
<<open_view MapView arg>>
```

| Parameter | Type   | Default  | Description       |
| --------- | ------ | -------- | ----------------- |
| `name`    | string | required | View identifier   |
| `arg`     | string | `null`   | Optional argument |

### open\_view\_overlay

Opens a view as an overlay.

```yarn theme={null}
<<open_view_overlay MapView>>
```

| Parameter | Type   | Default  | Description       |
| --------- | ------ | -------- | ----------------- |
| `name`    | string | required | View identifier   |
| `arg`     | string | `null`   | Optional argument |

### close\_view

Closes a UI view.

```yarn theme={null}
<<close_view GuildView>>
```

| Parameter | Type   | Description   |
| --------- | ------ | ------------- |
| `name`    | string | View to close |

### close\_all\_view

Closes all open views.

```yarn theme={null}
<<close_all_view>>
```

### set\_style

Changes the dialogue box style.

```yarn theme={null}
<<set_style "bubble">>
<<set_style "normal">>
<<set_style center>>
```

| Parameter | Type   | Description                               |
| --------- | ------ | ----------------------------------------- |
| `style`   | string | Style identifier (bubble, normal, center) |

### toast

Shows a toast notification.

```yarn theme={null}
<<toast "Message">>
```

| Parameter | Type   | Default  | Description        |
| --------- | ------ | -------- | ------------------ |
| `value`   | string | required | Message to display |
| `argsStr` | string | `""`     | Optional arguments |

## Audio Commands

### set\_bgm

Changes the background music.

```yarn theme={null}
<<set_bgm "music_name">>
<<set_bgm "music_name" 0.5 0.5>>
<<set_bgm "">>
```

| Parameter     | Type   | Default  | Description                      |
| ------------- | ------ | -------- | -------------------------------- |
| `name`        | string | required | Music track name (empty to stop) |
| `fadeOutTime` | float  | `0`      | Fade out duration                |
| `fadeInTime`  | float  | `0`      | Fade in duration                 |

### play\_sound\_effect

Plays a sound effect.

```yarn theme={null}
<<play_sound_effect "sound_name">>
```

| Parameter | Type   | Description       |
| --------- | ------ | ----------------- |
| `name`    | string | Sound effect name |

## Location Commands

### set\_current\_place

Sets the current map location.

```yarn theme={null}
<<set_current_place 9>>
```

| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `placeID` | int  | Location ID |

### set\_available\_place

Sets available map locations.

```yarn theme={null}
<<set_available_place "1,2,3,9">>
```

| Parameter | Type   | Description               |
| --------- | ------ | ------------------------- |
| `places`  | string | Comma-separated place IDs |

### set\_available\_mapEvent

Sets available map events.

```yarn theme={null}
<<set_available_mapEvent "10001,10002">>
```

| Parameter   | Type   | Description               |
| ----------- | ------ | ------------------------- |
| `mapEvents` | string | Comma-separated event IDs |

## Miscellaneous

### set\_player\_name

Sets the player's name.

```yarn theme={null}
<<set_player_name "Hero">>
```

| Parameter | Type   | Description |
| --------- | ------ | ----------- |
| `name`    | string | Player name |

### save\_game

Saves the game at a specific node.

```yarn theme={null}
<<save_game "NodeName">>
```

| Parameter  | Type   | Description           |
| ---------- | ------ | --------------------- |
| `nodeName` | string | Save point identifier |

### return\_to\_main\_view

Returns to the main game view.

```yarn theme={null}
<<return_to_main_view>>
```

### line\_show / line\_hide

Shows or hides the dialogue line.

```yarn theme={null}
<<line_show>>
<<line_hide>>
```

### set\_auto\_advance

Enables or disables auto-advance.

```yarn theme={null}
<<set_auto_advance true>>
<<set_auto_advance false>>
```

| Parameter | Type | Description         |
| --------- | ---- | ------------------- |
| `valid`   | bool | Enable auto-advance |

### wait\_input

Waits for player input.

```yarn theme={null}
<<wait_input>>
```

### wait\_time\_anim

Waits for time animation to complete.

```yarn theme={null}
<<wait_time_anim>>
```

## Common Patterns

### Quest Completion

```yarn theme={null}
<<change_gold 500>>
<<change_item 10050 1 true>>
<<change_affection 1002 20>>
<<event_end>>
```

### Shop Transaction

```yarn theme={null}
<<if get_gold() >= 100>>
    <<change_gold -100>>
    <<change_item 10001 1>>
    Shopkeeper: Here you go!
<<else>>
    Shopkeeper: You don't have enough gold.
<<endif>>
```

### Time Progression

```yarn theme={null}
<<next_period>>
<<set_bgm "music_evening">>
```

### Scene End

```yarn theme={null}
<<char_remove "Lilith">>
<<event_end>>
```