### Setup Rust Environment

Source: https://github.com/smly/riichienv/blob/main/docs/DEVELOPMENT_GUIDE.md

Downloads and installs the Rust toolchain using rustup.

```bash
curl --proto '=https' --tlsv1.2 https://sh.rustup.rs -sSf | sh
```

--------------------------------

### Start UI Development Server

Source: https://github.com/smly/riichienv/blob/main/docs/DEVELOPMENT_GUIDE.md

Start a local development server with hot-reloading for UI development.

```bash
cd riichienv-ui
npm run dev
```

--------------------------------

### Install Development Dependencies

Source: https://github.com/smly/riichienv/blob/main/docs/DEVELOPMENT_GUIDE.md

Installs development dependencies using uv.

```bash
uv sync --dev
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/smly/riichienv/blob/main/riichienv-ui/DEVELOPMENT_GUIDE.md

Navigate to the project directory and install Node.js dependencies using npm.

```bash
cd riichienv-ui
npm install
```

--------------------------------

### Start Development Server

Source: https://github.com/smly/riichienv/blob/main/riichienv-ui/DEVELOPMENT_GUIDE.md

Run a local development server with hot-reloading for rapid development.

```bash
npm run dev
```

--------------------------------

### Install UI Dependencies and Build

Source: https://github.com/smly/riichienv/blob/main/docs/DEVELOPMENT_GUIDE.md

Install Node.js dependencies and build the UI project. This runs the full build pipeline.

```bash
cd riichienv-ui
npm install
npm run build
```

--------------------------------

### Train PPO Algorithm

Source: https://github.com/smly/riichienv/blob/main/riichienv-ml/README.md

Starts training using the PPO algorithm with a specified configuration file.

```sh
uv run python scripts/train_ppo.py -c src/riichienv_ml/configs/4p/ppo.yml
```

--------------------------------

### Install RiichiEnv from source with Rust

Source: https://github.com/smly/riichienv/blob/main/README.md

If building from source, ensure you have the Rust toolchain installed. This command synchronizes development dependencies and builds the Rust core.

```bash
uv sync --dev
uv run maturin develop --release
```

--------------------------------

### Train BC with PPO

Source: https://github.com/smly/riichienv/blob/main/riichienv-ml/README.md

Starts training using BC with PPO, using a specified configuration file. Requires an online teacher, which is not included in the repository.

```sh
uv run python scripts/train_ppo.py -c src/riichienv_ml/configs/4p/bc_ppo.yml
```

--------------------------------

### Train CQL Algorithm

Source: https://github.com/smly/riichienv/blob/main/riichienv-ml/README.md

Starts training using the CQL algorithm with a specified configuration file.

```sh
uv run python scripts/train_cql.py -c src/riichienv_ml/configs/4p/cql.yml
```

--------------------------------

### Train Grouping Algorithm

Source: https://github.com/smly/riichienv/blob/main/riichienv-ml/README.md

Starts training using the Grouping algorithm with a specified configuration file.

```sh
uv run python scripts/train_grp.py -c src/riichienv_ml/configs/4p/grp.yml
```

--------------------------------

### Train BC Model

Source: https://github.com/smly/riichienv/blob/main/riichienv-ml/README.md

Starts training a BC model with a specified configuration file. Requires an online teacher, which is not included in the repository.

```sh
uv run python scripts/train_bc.py -c src/riichienv_ml/configs/4p/bc_model.yml
```

--------------------------------

### Commit Message Examples

Source: https://github.com/smly/riichienv/blob/main/docs/DEVELOPMENT_GUIDE.md

Examples of commit messages following the Conventional Commits format.

```text
feat(env): add Kyoku.events serialization
fix(score): correct ura dora calculation
docs(readme): update installation instructions
```

--------------------------------

### Build Python Extension

Source: https://github.com/smly/riichienv/blob/main/docs/DEVELOPMENT_GUIDE.md

Builds and installs the Python extension into the virtual environment using maturin.

```bash
uv run maturin develop
```

--------------------------------

### Install RiichiEnv using uv or pip

Source: https://github.com/smly/riichienv/blob/main/README.md

Install the RiichiEnv package using either the uv or pip package manager. This is the primary method for adding the library to your project.

```bash
uv add riichienv
# Or
pip install riichienv
```

--------------------------------

### Get Game Summary

Source: https://github.com/smly/riichienv/blob/main/riichienv-ui/demos/README.md

Retrieve a list of dictionaries, each summarizing a round (kyoku) of the game.

```python
>>> viewer.summary()
[
    {'round_idx': 0, 'bakaze': 'E', 'kyoku': 1, 'honba': 0, 'oya': 0, 'scores': [25000, 25000, 25000, 25000]},
    {'round_idx': 1, 'bakaze': 'E', 'kyoku': 2, 'honba': 0, 'oya': 1, 'scores': [33000, 25000, 17000, 25000]},
    ...
]
```

--------------------------------

### Build Optimized Python Extension

Source: https://github.com/smly/riichienv/blob/main/docs/DEVELOPMENT_GUIDE.md

Builds and installs an optimized release version of the Python extension using maturin.

```bash
uv run maturin develop --release
```

--------------------------------

### Observe Discard Event for Player Actions (Pon/Ron)

Source: https://github.com/smly/riichienv/blob/main/README.md

This example demonstrates how `observe_event` can detect if a player has legal actions (like 'pon' or 'ron') after an opponent's discard. The observation will be non-`None` if the player can react to the discard.

```python
# 4P example: P1 can pon after P0's discard
env = RiichiEnv(game_mode="default")
env.observe_event({"type": "start_game"}, player_id=1)
env.observe_event({"type": "start_kyoku", ...}, player_id=1)
env.observe_event({"type": "tsumo", "actor": 0, "pai": "?"}, player_id=1)

obs = env.observe_event(
    {"type": "dahai", "actor": 0, "pai": "5m", "tsumogiri": True},
    player_id=1,
)
# obs is not None if player 1 can pon/ron the discarded tile
if obs is not None:
    for a in obs.legal_actions():
        print(a.to_mjai())  # e.g. pon, pass
```

--------------------------------

### Control Game Visualization Display

Source: https://github.com/smly/riichienv/blob/main/README.md

Shows how to display a specific step of the game or change the camera perspective in the 3D viewer. Also shows how to get round summary and results.

```python
viewer = env.get_viewer()
viewer.show(step=100, perspective=0)  # show() accepts optional display parameters
viewer.summary()        # list of round info dicts (bakaze, kyoku, honba, oya, scores)
viewer.get_results(0)   # list[WinResult] for round 0
```

--------------------------------

### Reset Environment and Get Initial Observations

Source: https://github.com/smly/riichienv/blob/main/README.md

Resets the RiichiEnv environment to its initial state and retrieves the observations for all active players. The output shows the structure of the observation dictionary.

```python
from riichienv import RiichiEnv
env = RiichiEnv()
obs_dict = env.reset()
print(obs_dict)
```

--------------------------------

### Get Legal Actions for a Player

Source: https://github.com/smly/riichienv/blob/main/README.md

Retrieves a list of all valid actions a player can take in the current game state. Actions are represented by an `Action` object.

```python
obs.legal_actions()
```

--------------------------------

### Simulate a Mahjong Game Turn in Rust

Source: https://github.com/smly/riichienv/blob/main/riichienv-core/README.md

Initializes a game state with Tenhou rules, gets the current player's observation and legal actions, and advances the game state by one step. Requires `riichienv_core::state::GameState` and `riichienv_core::rule::GameRule`.

```rust
use riichienv_core::state::GameState;
use riichienv_core::rule::GameRule;
use std::collections::HashMap;

// Create a new game with Tenhou rules
// GameState::new(game_mode, skip_mjai_logging, seed, round_wind, rule)
let rule = GameRule::default_tenhou();
let mut state = GameState::new(0, true, None, 0, rule);

// Get observation for the current player
let obs = state.get_observation(0);
let legal_actions = obs.legal_actions_method();

// Advance the game state (actions is a HashMap<u8, Action>)
let mut actions = HashMap::new();
actions.insert(0, legal_actions[0].clone());
state.step(&actions);
```

--------------------------------

### Apply MJAI Event and Get Observation

Source: https://github.com/smly/riichienv/blob/main/README.md

Use `observe_event` for online inference, feeding events one at a time and acting when a non-`None` observation is returned. This method handles the complexity of determining when a player needs to act, including reaction phases.

```python
env = RiichiEnv(game_mode="3p-red-half")
my_seat = 0

for event in mjai_events:
    obs = env.observe_event(event, my_seat)
    if obs is not None:
        # This player needs to act
        action = select_action(obs)  # your model logic
        ...
```

--------------------------------

### Get New MJAI Events for a Player

Source: https://github.com/smly/riichienv/blob/main/README.md

Retrieves a list of new MJAI JSON events for a specific player since their last observation. This can include game start, round start, and tile draws.

```python
obs = obs_dict[0]
obs.new_events()
```

--------------------------------

### Switch Branch and Run Benchmark

Source: https://github.com/smly/riichienv/blob/main/docs/DEVELOPMENT_GUIDE.md

Checkout a feature branch and run benchmarks against a baseline.

```bash
git checkout feature-branch
cargo bench --bench agari_bench -- --baseline main
```

--------------------------------

### Initialize RiichiViewer (Recommended API)

Source: https://github.com/smly/riichienv/blob/main/riichienv-ui/README.md

Mount the RiichiViewer to a container element and configure its behavior. The viewer emits events for various game state changes.

```typescript
import { RiichiViewer } from 'riichienv-ui';

const viewer = RiichiViewer.mount('container-id', {
    log: events,           // MjaiEvent[]
    renderer: '3d',        // '2d' or '3d' (default: '3d')
    perspective: 0,        // player viewpoint (0-3)
    freeze: false,         // disable controls
    initialPosition: { kyoku: 0 },
});

viewer.on('positionChange', ({ kyokuIndex, step }) => { ... });
viewer.on('kyokuChange', ({ kyokuIndex, round, honba }) => { ... });
viewer.on('viewpointChange', ({ viewpoint }) => { ... });
viewer.destroy();
```

--------------------------------

### Initialize and Run a Game with Random Agent

Source: https://github.com/smly/riichienv/blob/main/README.md

Demonstrates initializing the RiichiEnv environment and using a RandomAgent to play through a game. The environment resets, and the agent selects actions until the game is done. Finally, it prints the scores and ranks.

```python
from riichienv import RiichiEnv
from riichienv.agents import RandomAgent

agent = RandomAgent()
env = RiichiEnv()
obs_dict = env.reset()
while not env.done():
    actions = {player_id: agent.act(obs)
               for player_id, obs in obs_dict.items()}
    obs_dict = env.step(actions)

scores, ranks = env.scores(), env.ranks()
print(scores, ranks)
```

--------------------------------

### Initialize and Run a Mahjong Game with Random Agent

Source: https://github.com/smly/riichienv/blob/main/README.md

Initializes a RiichiEnv environment and a RandomAgent, then runs a game until completion. The game state is observed at each step.

```python
from riichienv import RiichiEnv
from riichienv.agents import RandomAgent

agent = RandomAgent()
env = RiichiEnv(game_mode="4p-red-half")
obs_dict = env.reset()
while not env.done():
    actions = {pid: agent.act(obs) for pid, obs in obs_dict.items()}
    obs_dict = env.step(actions)

env.get_viewer().show()  # displays the 3D viewer in Jupyter
```

--------------------------------

### Direct Constructors (via script tag)

Source: https://github.com/smly/riichienv/blob/main/riichienv-ui/README.md

When the viewer is loaded via a script tag, several global constructors are exposed on the `window` object, allowing direct instantiation of 2D, 3D, and live viewers.

```APIDOC
## Direct Constructors (via script tag)

### Description
When `dist/viewer.js` is included directly in an HTML file via a `<script>` tag, the following viewer classes are exposed as global variables on the `window` object, enabling direct instantiation.

### Available Globals
- `window.RiichiViewer`: High-level API class (same as imported `RiichiViewer`).
- `window.RiichiEnvViewer`: 2D replay viewer class.
- `window.RiichiEnv3DViewer`: 3D replay viewer class.
- `window.RiichiEnvLiveViewer`: Live game viewer class.

### Usage Examples

#### 3D Viewer
```javascript
// Assuming 'events' is an array of Maji events
new RiichiEnv3DViewer('container-id', events);
```

#### 2D Viewer
```javascript
// Assuming 'events' is an array of Maji events
new RiichiEnvViewer('container-id', events);
```
```

--------------------------------

### Get Winning Results for a Round

Source: https://github.com/smly/riichienv/blob/main/riichienv-ui/demos/README.md

Fetch a list of WinResult objects for a specific round, detailing the outcome of the hand.

```python
>>> results = viewer.get_results(0)
>>> for r in results:
...     print(r)
WinResult(is_win=True, yakuman=False, ron_agari=7700, ...)

>>> results[0].yaku_list()
[Yaku(id=14, name='平和', name_en='Pinfu', ...), ...]
```

--------------------------------

### Python Wrapper for Sequence Feature Encoding

Source: https://github.com/smly/riichienv/blob/main/docs/SEQUENCE_FEATURE_ENCODING.md

Example usage of the SequenceFeatureEncoder from riichienv_ml.features.sequence_features to encode game observations into various feature tensors.

```python
from riichienv import RiichiEnv
from riichienv_ml.features.sequence_features import SequenceFeatureEncoder

env = RiichiEnv(game_mode="4p-red-half")
obs_dict = env.reset()
enc = SequenceFeatureEncoder(n_players=4, game_style=1)

for pid, obs in obs_dict.items():
    features = enc.encode(obs)
    # features["sparse"]      -- (25,) int64, padded with 441
    # features["numeric"]     -- (12,) float32
    # features["progression"] -- (256, 5) int64, padded with (4, 276, 2, 2, 4)
    # features["candidates"]  -- (32, 4) int64, padded with (279, 2, 2, 3)
    # features["sparse_mask"] -- (25,) bool, True for real tokens
    # features["prog_mask"]   -- (256,) bool, True for real entries
    # features["cand_mask"]   -- (32,) bool, True for real entries
```

--------------------------------

### Initialize LiveViewer for Real-time Updates

Source: https://github.com/smly/riichienv/blob/main/riichienv-ui/README.md

Instantiate the LiveViewer and push events incrementally to visualize live game progress. Wait tiles are calculated automatically if not pre-computed.

```typescript
import { LiveViewer } from 'riichienv-ui';

const viewer = new LiveViewer(container, { viewpoint: 0 });
viewer.pushEvent({ type: 'start_kyoku', ... });
viewer.pushEvent({ type: 'tsumo', ... });
```

--------------------------------

### Run Correctness Tests

Source: https://github.com/smly/riichienv/blob/main/docs/DEVELOPMENT_GUIDE.md

Navigate to the core directory and execute the correctness tests.

```bash
cd riichienv-core
cargo test --test agari_correctness
```

--------------------------------

### Build RiichiEnv UI

Source: https://github.com/smly/riichienv/blob/main/riichienv-ui/DEVELOPMENT_GUIDE.md

Compile TypeScript, build WASM, and bundle the viewer for production.

```bash
npm run build
```

--------------------------------

### Place Font File

Source: https://github.com/smly/riichienv/blob/main/riichienv-ui/DEVELOPMENT_GUIDE.md

Copy the downloaded Zen Antique Soft font file into the assets directory.

```bash
riichienv-ui/assets/ZenAntiqueSoft-Regular.ttf
```

--------------------------------

### Get Detailed Yaku Information from Win Result

Source: https://github.com/smly/riichienv/blob/main/README.md

Retrieves detailed information about the Yaku (scoring hands) present in a WinResult object. This provides names and IDs for each Yaku.

```python
>>> result = he.calc(cvt.mpsz_to_tid("3s"), dora_indicators=[], ura_indicators=[])
>>> for y in result.yaku_list():
...     print(y)
Yaku(id=8, name='役牌 發', name_en='Yakuhai (hatsu)', tenhou_id=19, mjsoul_id=8)
Yaku(id=11, name='場風牌', name_en='Yakuhai (round wind)', tenhou_id=14, mjsoul_id=11)
Yaku(id=10, name='自風牌', name_en='Yakuhai (seat wind)', tenhou_id=10, mjsoul_id=10)
Yaku(id=22, name='三暗刻', name_en='San Ankou', tenhou_id=29, mjsoul_id=22)
```

--------------------------------

### Initialize RiichiViewer with Custom Player Data

Source: https://github.com/smly/riichienv/blob/main/riichienv-ui/player_custom_demo.html

Mounts the RiichiViewer to a specified element, loads a game log from a JSONL file, and configures player details including names and avatar URLs. Ensure RiichiViewer is loaded before this script.

```javascript
if (typeof RiichiViewer === 'undefined') { document.getElementById('viewer').textContent = 'Error: RiichiViewer not loaded.'; } else { fetch('example_after_injection.jsonl') .then(r => { if (!r.ok) throw new Error('Failed to fetch JSONL: ' + r.status); return r.text(); }) .then(text => { const log = text.trim().split('\n').map(line => JSON.parse(line)); const viewer = RiichiViewer.mount('viewer', { log: log, renderer: '3d', players: [ { name: 'smlybot0', avatarUrl: 'https://avatars.githubusercontent.com/u/19337?v=4' }, { name: 'smlybot1', avatarUrl: 'https://avatars.githubusercontent.com/u/19337?v=4' }, { name: 'smlybot2', avatarUrl: 'https://avatars.githubusercontent.com/u/19337?v=4' }, { name: 'smlybot3', avatarUrl: 'https://avatars.githubusercontent.com/u/19337?v=4' }, ], }); const playerNames = viewer.getPlayerNames(); const summaries = viewer.getKyokuSummaries(); const winds = ['E', 'S', 'W', 'N']; const windFull = { E: 'East', S: 'South', W: 'West', N: 'North' }; const pc = playerNames.length; function roundLabel(round, honba) { const w = winds[Math.floor(round / pc)] || 'E'; const r = (round % pc) + 1; return windFull[w] + ' ' + r + (honba > 0 ? ' - ' + honba : ''); } // --- Build kyoku list --- const listEl = document.getElementById('kyoku-list'); const items = []; summaries.forEach((s, idx) => { const item = document.createElement('div'); item.className = 'kyoku-item'; // Header row const header = document.createElement('div'); header.className = 'kyoku-item-header'; const roundEl = document.createElement('span'); roundEl.className = 'kyoku-round'; roundEl.textContent = roundLabel(s.round, s.honba); header.appendChild(roundEl); const tag = document.createElement('span'); tag.className = 'kyoku-result-tag'; if (s.result) { if (s.result.type === 'hora') { const w = s.result.winners?.[0]; if (w?.isTsumo) { tag.classList.add('tag-tsumo'); tag.textContent = 'Tsumo'; } else { tag.classList.add('tag-ron'); tag.textContent = 'Ron'; } } else { tag.classList.add('tag-draw'); tag.textContent = s.result.reason || 'Draw'; } } header.appendChild(tag); item.appendChild(header); // Score deltas const scores = document.createElement('div'); scores.className = 'kyoku-scores'; for (let p = 0; p < pc; p++) { const chip = document.createElement('span'); chip.className = 'score-chip'; const d = s.deltas[p]; const cls = d > 0 ? 'pos' : d < 0 ? 'neg' : 'zero'; const sign = d > 0 ? '+' : ''; const nameSpan = document.createElement('span'); nameSpan.style.color = '#aaa'; nameSpan.textContent = shortName(playerNames[p]); chip.appendChild(nameSpan); chip.appendChild(document.createTextNode(' ')); const deltaSpan = document.createElement('span'); deltaSpan.className = 'score-delta ' + cls; deltaSpan.textContent = sign + d; chip.appendChild(deltaSpan); scores.appendChild(chip); } item.appendChild(scores); // Player action badges const badges = document.createElement('div'); badges.className = 'player-badges'; for (let p = 0; p < pc; p++) { const a = s.playerActions[p]; if (a.tsumo) badges.appendChild(makeBadge(shortName(playerNames[p]) + ' Tsumo', 'badge-tsumo')); else if (a.hora) badges.appendChild(makeBadge(shortName(playerNames[p]) + ' Ron', 'badge-ron')); if (a.houjuu) badges.appendChild(makeBadge(shortName(playerNames[p]) + ' Deal-in', 'badge-houjuu')); if (a.riichi) badges.appendChild(makeBadge(shortName(playerNames[p]) + ' Riichi', 'badge-riichi')); if (a.meldTypes.length > 0) badges.appendChild(makeBadge(shortName(playerNames[p]) + ' Meld', 'badge-meld')); if (a.tenpai && !a.hora) badges.appendChild(makeBadge(shortName(playerNames[p]) + ' Tenpai', 'badge-tenpai')); } item.appendChild(badges); item.onclick = () => selectKyoku(idx); listEl.appendChild(item); items.push(item); }); let selectedKyoku = -1; let keyEventsCache = {}; function selectKyoku(idx) { selectedKyoku = idx; items.forEach((el, i) => el.classList.toggle('active', i === idx)); viewer.goToKyoku(idx); // Get key events (cached) if (!keyEventsCache[idx]) { keyEventsCache[idx] = viewer.getKyokuKeyEvents(idx); } renderDetail(summaries[idx], keyEventsCache[idx]); } function renderDetail(summary, keyEvents) { const detail = document.getElementById('kyoku-detail'); detail.innerHTML = ''; // Result section if (summary.result) { const sec = makeSection('Result'); if (summary.result.type === 'hora' && summary.result.winners) { summary.result.winners.forEach(w => { const block = document.createElement('div'); block.className = 'result-winner'; const hdr = document.createElement('div'); hdr.className = 'result-winner-header'; const name = document.createElement('span'); name.className = 'result-winner-name'; const winType = w.isTsumo ? 'Tsumo' : 'Ron'; const fromStr = w.isTsumo ? '' : ` from ${playerNames[w.target]}`; name.textContent = `${playerNames[w.actor]} - ${winType}${fromStr}`; hdr.appendChild(name); const pts = document.createElement('span'); pts.className = 'result-winner-points'; pts.textContent = w.points > 0
```

--------------------------------

### RiichiViewer.mount()

Source: https://github.com/smly/riichienv/blob/main/riichienv-ui/README.md

The recommended high-level API for mounting the RiichiEnv viewer. It initializes the viewer within a specified container and accepts game events for playback or live viewing. Event listeners can be attached for various game state changes.

```APIDOC
## RiichiViewer.mount()

### Description
Initializes and mounts the RiichiEnv viewer into a specified HTML element. This is the recommended API for integrating the viewer, supporting both replay and live game modes.

### Method
`RiichiViewer.mount(containerId: string, options?: ViewerOptions)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

#### `ViewerOptions` (Object)
- **log** (MjaiEvent[]) - Required - An array of Maji events representing the game log.
- **renderer** (string) - Optional - The rendering mode, either '2d' or '3d'. Defaults to '3d'.
- **perspective** (number) - Optional - The player viewpoint (0-3). Defaults to 0.
- **freeze** (boolean) - Optional - If true, disables user controls. Defaults to false.
- **initialPosition** (object) - Optional - Specifies the initial game position.
  - **kyoku** (number) - Optional - The initial kyoku index.

### Events
- **positionChange**: Emitted when the playback position changes.
- **kyokuChange**: Emitted when a new kyoku begins.
- **viewpointChange**: Emitted when the player's viewpoint changes.

### Usage Example
```typescript
import { RiichiViewer } from 'riichienv-ui';

const viewer = RiichiViewer.mount('container-id', {
    log: events,
    renderer: '3d',
    perspective: 0,
    freeze: false,
    initialPosition: { kyoku: 0 },
});

viewer.on('positionChange', ({ kyokuIndex, step }) => { /* ... */ });
viewer.on('kyokuChange', ({ kyokuIndex, round, honba }) => { /* ... */ });
viewer.on('viewpointChange', ({ viewpoint }) => { /* ... */ });

// To clean up the viewer instance:
viewer.destroy();
```
```

--------------------------------

### Helper Function: Dot Class for Events

Source: https://github.com/smly/riichienv/blob/main/riichienv-ui/player_custom_demo.html

Determines the CSS class for an event dot based on the event type. Melds (chi, pon, kan) get the 'meld' class.

```javascript
function dotClass(type) {
 if (['chi', 'pon', 'daiminkan', 'ankan', 'kakan'].includes(type)) return 'meld';
 return type;
}
```

--------------------------------

### Create Viewer from JSONL File

Source: https://github.com/smly/riichienv/blob/main/riichienv-ui/demos/README.md

Load game events from a JSONL file to create a GameViewer instance.

```python
viewer = GameViewer.from_jsonl("path/to/game.jsonl")
viewer.show(step=100, perspective=0)
```

--------------------------------

### Watch for Changes and Rebuild

Source: https://github.com/smly/riichienv/blob/main/riichienv-ui/DEVELOPMENT_GUIDE.md

Continuously watch for file changes and rebuild the project.

```bash
npm run watch
```

--------------------------------

### Build UI Only (Skip WASM)

Source: https://github.com/smly/riichienv/blob/main/docs/DEVELOPMENT_GUIDE.md

Build only the UI components, skipping the WASM rebuild process.

```bash
cd riichienv-ui
npm run build:no-wasm
```

--------------------------------

### LiveViewer.pushEvent()

Source: https://github.com/smly/riichienv/blob/main/riichienv-ui/README.md

The `LiveViewer` class is designed for real-time game visualization. It accepts game events incrementally using the `pushEvent` method, allowing for dynamic updates as the game progresses. It also automatically calculates wait tiles when WASM is loaded and hands lack pre-computed wait data.

```APIDOC
## LiveViewer.pushEvent()

### Description
Processes game events incrementally for real-time visualization. The `LiveViewer` class updates the display as new events are pushed, and automatically handles WASM-based wait tile calculations when available.

### Method
`viewer.pushEvent(event: MajiEvent)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

#### `event` (MajiEvent)
An object representing a single game event (e.g., `start_kyoku`, `tsumo`, `discard`).

### Usage Example
```typescript
import { LiveViewer } from 'riichienv-ui';

// Assuming 'container' is an HTML element
const viewer = new LiveViewer(container, { viewpoint: 0 });

// Push events as they occur in a live game
viewer.pushEvent({ type: 'start_kyoku', ... });
viewer.pushEvent({ type: 'tsumo', ... });
viewer.pushEvent({ type: 'discard', ... });

// The viewer automatically calculates waits if WASM is loaded and meta.waits is missing.
```
```

--------------------------------

### Run UI File Watcher

Source: https://github.com/smly/riichienv/blob/main/docs/DEVELOPMENT_GUIDE.md

Use a file watcher for automatic rebuilds during UI development.

```bash
cd riichienv-ui
npm run watch
```

--------------------------------

### Instantiate 2D Viewer via Script Tag

Source: https://github.com/smly/riichienv/blob/main/riichienv-ui/README.md

Create a new 2D viewer instance when the script is loaded globally.

```javascript
// 2D viewer
new RiichiEnvViewer('container-id', events);
```

--------------------------------

### Instantiate 3D Viewer via Script Tag

Source: https://github.com/smly/riichienv/blob/main/riichienv-ui/README.md

Create a new 3D viewer instance when the script is loaded globally.

```javascript
// 3D viewer
new RiichiEnv3DViewer('container-id', events);
```

--------------------------------

### Create Viewer from RiichiEnv Instance

Source: https://github.com/smly/riichienv/blob/main/riichienv-ui/demos/README.md

Instantiate a GameViewer from an active RiichiEnv instance after a game has been played.

```python
from riichienv import RiichiEnv
from riichienv.agents import RandomAgent

agent = RandomAgent()
env = RiichiEnv(game_mode="4p-red-half")
obs_dict = env.reset()
while not env.done():
    actions = {pid: agent.act(obs) for pid, obs in obs_dict.items()}
    obs_dict = env.step(actions)

env.get_viewer().show()
```

--------------------------------

### Load and Display Replay Data

Source: https://github.com/smly/riichienv/blob/main/riichienv-ui/index.html

Fetches replay data from a JSONL file, parses it, and initializes the RiichiEnv 3D Viewer. Ensure the 'viewer-container' element exists in your HTML and the RiichiEnv3DViewer is globally available.

```javascript
async function loadReplay() {
  try {
    // Fetch the example log
    const response = await fetch('example_before_injection.jsonl');
    const text = await response.text();

    // Parse JSONL
    const events = text.trim().split('\n').map(line => JSON.parse(line));

    // Initialize 3D Viewer
    if (window.RiichiEnv3DViewer) {
      new window.RiichiEnv3DViewer('viewer-container', events);
    } else {
      console.error('RiichiEnv3DViewer not found');
    }
  } catch (err) {
    console.error('Failed to load replay:', err);
    document.body.innerHTML += `<div style="color: red;">Error: ${err.message}</div>`;
  }
}

loadReplay();
```

--------------------------------

### Load and Visualize Game Replay from JSONL

Source: https://github.com/smly/riichienv/blob/main/riichienv-ui/demos/replay_demo.ipynb

Loads a game replay from a JSONL file and visualizes a specific step of the game. The viewer can be configured to show perspective and whether to freeze the frame.

```python
# Load from JSONL file
log_path = '../example_before_injection.jsonl'
viewer = GameViewer.from_jsonl(log_path)
viewer.show(step=442, perspective=0, freeze=False)
```

--------------------------------

### Lint and Format Code with Biome

Source: https://github.com/smly/riichienv/blob/main/riichienv-ui/DEVELOPMENT_GUIDE.md

Use Biome to check for linting issues and format the project's source files.

```bash
npm run lint
```

```bash
npm run lint:fix
```

```bash
npm run format
```

```bash
npm run format:check
```

--------------------------------

### Format Python Code with Ruff

Source: https://github.com/smly/riichienv/blob/main/docs/DEVELOPMENT_GUIDE.md

Apply code formatting to the entire project using `ruff format`.

```bash
uv run ruff format .
```

--------------------------------

### Create Viewer from List of Events

Source: https://github.com/smly/riichienv/blob/main/riichienv-ui/demos/README.md

Construct a GameViewer from a Python list of event dictionaries.

```python
events = [{"type": "start_game", ...}, ...]
viewer = GameViewer.from_list(events)
viewer.show(step=50, freeze=True)
```

--------------------------------

### Import GameViewer

Source: https://github.com/smly/riichienv/blob/main/riichienv-ui/demos/README.md

Import the GameViewer class from the riichienv.visualizer module.

```python
from riichienv.visualizer import GameViewer
```

--------------------------------

### Synchronize Dependencies

Source: https://github.com/smly/riichienv/blob/main/riichienv-ml/README.md

Synchronizes project dependencies using uv.

```sh
uv sync
```

--------------------------------

### Save Baseline for Rust Benchmarks

Source: https://github.com/smly/riichienv/blob/main/docs/DEVELOPMENT_GUIDE.md

Save a baseline for Rust benchmarks to compare performance across different branches.

```bash
cargo bench --bench agari_bench -- --save-baseline main
```

--------------------------------

### Initialize Custom Game Rules

Source: https://github.com/smly/riichienv/blob/main/README.md

Initializes a RiichiEnv environment with custom game rules based on Tenhou presets, enabling Kokushi Chankan and setting a specific round length.

```python
from riichienv import RiichiEnv, GameRule

# Example 2: Fully custom rules based on Tenhou preset
rule_custom = GameRule.default_tenhou()
rule_custom.allows_ron_on_ankan_for_kokushi_musou = True  # Enable Kokushi Chankan
rule_custom.length_of_game_in_rounds = 8  # Force 8 rounds? (Note: Length is mainly controlled by game_mode logic usually)

env = RiichiEnv(game_mode="4p-red-half", rule=rule_custom)
```

--------------------------------

### Run Rust Benchmarks

Source: https://github.com/smly/riichienv/blob/main/docs/DEVELOPMENT_GUIDE.md

Execute Criterion-based benchmarks for Rust code, specifically the agari detection benchmark.

```bash
cd riichienv-core
cargo bench --bench agari_bench
```

--------------------------------

### Initialize Standard 4-Player Hanchan Game

Source: https://github.com/smly/riichienv/blob/main/README.md

Initializes a RiichiEnv environment with a standard 4-player Hanchan game mode.

```python
# Initialize a standard 4-player Hanchan game
env = RiichiEnv(game_mode="4p-red-half")
```

--------------------------------

### Initialize MJSoul Game Rules

Source: https://github.com/smly/riichienv/blob/main/README.md

Initializes a RiichiEnv environment with MJSoul game rules, which allows Ron on Ankan for Kokushi Musou.

```python
from riichienv import RiichiEnv, GameRule

# Example 1: Use MJSoul rules (allows Ron on Ankan for Kokushi Musou)
rule_mjsoul = GameRule.default_mjsoul()
env = RiichiEnv(game_mode="4p-red-half", rule=rule_mjsoul)
```

--------------------------------

### Run Tests with Vitest

Source: https://github.com/smly/riichienv/blob/main/riichienv-ui/DEVELOPMENT_GUIDE.md

Execute tests using Vitest, either once or in watch mode.

```bash
npm run test
```

```bash
npm run test:watch
```

--------------------------------

### Publish to crates.io

Source: https://github.com/smly/riichienv/blob/main/docs/DEVELOPMENT_GUIDE.md

Publish the Rust core library to crates.io after a successful dry run.

```bash
cargo publish -p riichienv-core
```

--------------------------------

### Publish to crates.io (Dry Run)

Source: https://github.com/smly/riichienv/blob/main/docs/DEVELOPMENT_GUIDE.md

Perform a dry run before publishing the Rust core library to crates.io to check for potential issues.

```bash
cargo publish -p riichienv-core --dry-run
```

--------------------------------

### Run Rust Unit Tests

Source: https://github.com/smly/riichienv/blob/main/docs/DEVELOPMENT_GUIDE.md

Executes Rust unit tests for the riichienv-core crate.

```bash
cargo test -p riichienv-core
```

--------------------------------

### Build WASM Module

Source: https://github.com/smly/riichienv/blob/main/docs/DEVELOPMENT_GUIDE.md

Build the WASM module for the web target using `wasm-pack`.

```bash
wasm-pack build riichienv-wasm --target web
```

--------------------------------

### Run Pre-commit Checks

Source: https://github.com/smly/riichienv/blob/main/CONTRIBUTING.md

Execute pre-commit checks to ensure code quality and consistency before submitting changes. This command verifies that all configured hooks pass.

```bash
uv run pre-commit run --config .pre-commit-config.yaml
```

--------------------------------

### Print Game Summary from Viewer

Source: https://github.com/smly/riichienv/blob/main/riichienv-ui/demos/replay_demo.ipynb

Iterates through the game summary provided by the GameViewer and prints the details of each round, including round index, wind, kyoku, honba, dealer, and scores.

```python
summary = viewer.summary()
for round_summary in summary:
    print(round_summary)
```

--------------------------------

### Displaying Key Events Timeline

Source: https://github.com/smly/riichienv/blob/main/riichienv-ui/player_custom_demo.html

Creates a timeline of key game events. If no events exist, it displays an 'empty-msg'. Each event is represented as a list item with a dot indicating its type.

```javascript
// Key events timeline
const eventSec = makeSection('Key Events');
if (keyEvents.length === 0) {
 eventSec.innerHTML += '<div class="empty-msg">No key events</div>';
} else {
 const list = document.createElement('ul');
 list.className = 'event-timeline';
 keyEvents.forEach(evt => {
  const li = document.createElement('li');
  li.className = 'event-item';
  const dot = document.createElement('div');
  dot.className = 'event-dot dot-' + dotClass(evt.type);
  li.appendChild(dot);
  const player = document.createElement('span');
  player.className = 'event-player';
  player.textContent = evt.actor >= 0 ? shortName(playerNames[evt.actor]) : '';
  li.appendChild(player);
  const label = document.createElement('span');
  label.className = 'event-label';
  label.textContent = evt.label;
  li.appendChild(label);
  if (evt.detail) {
   const det = document.createElement('span');
   det.className = 'event-detail';
   det.textContent = evt.detail;
   li.appendChild(det);
  }
  li.onclick = (e) => {
   e.stopPropagation();
   viewer.goToStep(evt.step + 1);
   // Highlight active list.querySelectorAll('.event-item').forEach(el => el.classList.remove('active-event'));
   li.classList.add('active-event');
  };
  list.appendChild(li);
 });
 eventSec.appendChild(list);
}
detail.appendChild(eventSec);
```

--------------------------------

### Simulate 3-Player Game with ML Agents

Source: https://github.com/smly/riichienv/blob/main/riichienv-ui/demos/replay_demo.ipynb

Simulates a 3-player game using pre-trained machine learning agents. It loads agent configurations and models, then runs the game until completion, printing final ranks and scores, and displaying the game viewer.

```python
from riichienv_ml.agents import Agent


CONFIG_PATH = "../../riichienv-ml/src/riichienv_ml/configs/3p/bc_logs.yml"
CONFIG3_PATH = "../../riichienv-ml/src/riichienv_ml/configs/3p/bc_ppo.yml"

MODEL_PATH = "/data/workspace/riichienv-ml/3p/bc_logs_2M.pth"
MODEL2_PATH = "/data/workspace/riichienv-ml/3p/bc_logs_2Mr2.pth"
MODEL3_PATH = "/data/workspace/riichienv-ml/3p/bc_ppo/checkpoints/model_500.pth"

agent = Agent(CONFIG_PATH, MODEL_PATH, device="cuda")
agent2 = Agent(CONFIG_PATH, MODEL2_PATH, device="cuda")
agent3 = Agent(CONFIG3_PATH, MODEL3_PATH, device="cuda")
agents = {0: agent, 1: agent2, 2: agent3}

env = RiichiEnv(game_mode="3p-red-half")
obs_dict = env.reset()

while not env.done():
    actions = {pid: agents[pid].act(obs) for pid, obs in obs_dict.items()}
    obs_dict = env.step(actions)

print(env.ranks(), env.scores())
env.get_viewer().show()
```

--------------------------------

### Compare Shanten Calculation for 3P vs 4P

Source: https://github.com/smly/riichienv/blob/main/README.md

Demonstrates a corner case where shanten calculation can differ between 3-player and 4-player Mahjong due to tile availability. Uses parse_hand to process tile input.

```python
>>> tiles, _ = parse_hand("1111m111122233z")
>>> calculate_shanten(tiles), calculate_shanten_3p(tiles)
(1, 2)  # 4P tenpai path requires drawing 2m/3m, which don't exist in 3P
```

--------------------------------

### Run Python Unit Tests

Source: https://github.com/smly/riichienv/blob/main/docs/DEVELOPMENT_GUIDE.md

Execute the Python test suite using `pytest`.

```bash
uv run pytest
```

--------------------------------

### Run Python Linter with Ruff

Source: https://github.com/smly/riichienv/blob/main/docs/DEVELOPMENT_GUIDE.md

Check for linting errors in the Python code using `ruff check`.

```bash
uv run ruff check .
```

--------------------------------

### Format Rust Code

Source: https://github.com/smly/riichienv/blob/main/docs/DEVELOPMENT_GUIDE.md

Formats all Rust code in the project using rustfmt.

```bash
cargo fmt
```

--------------------------------

### Display GameViewer in Jupyter

Source: https://github.com/smly/riichienv/blob/main/riichienv-ui/demos/README.md

Show the GameViewer in a Jupyter Notebook. It can auto-render or be explicitly shown using show().

```python
viewer = env.get_viewer()
viewer          # auto-renders in Jupyter via _repr_html_
viewer.show()   # returns IPython.display.HTML
viewer.show(step=100, perspective=0, freeze=True)
```

--------------------------------

### Encode Shanten and Efficiency Features

Source: https://github.com/smly/riichienv/blob/main/docs/FEATURE_ENCODING.md

Demonstrates how to retrieve and unpack the encoded shanten and efficiency features from the environment's observation. It shows how to access individual player features and denormalize them to their actual values.

```python
import riichienv as renv
import struct

env = renv.RiichiEnv()
obs_dict = env.reset()
obs = obs_dict[0]

# Get shanten and efficiency features
encoded_bytes = obs.encode_shanten_efficiency()
values = struct.unpack('16f', encoded_bytes)  # 4 players × 4 features

# Player 0 (self) features
shanten_norm = values[0]        # Normalized shanten
effective_norm = values[1]      # Normalized effective tile types
ukeire_norm = values[2]         # Normalized best ukeire
turn_norm = values[3]           # Normalized turn count

# Denormalize
actual_shanten = shanten_norm * 8.0
effective_types = effective_norm * 34.0
best_ukeire = ukeire_norm * 80.0
turn_number = turn_norm * 18.0

print(f"Shanten: {actual_shanten:.1f}")
print(f"Effective tile types: {effective_types:.0f}")
print(f"Best ukeire: {best_ukeire:.0f} tiles")
print(f"Turn: {turn_number:.0f}")
```

--------------------------------

### Bump Version and Commit

Source: https://github.com/smly/riichienv/blob/main/docs/DEVELOPMENT_GUIDE.md

Update version numbers in multiple Cargo.toml and pyproject.toml files, then commit and push the changes.

```bash
git add riichienv-core/Cargo.toml riichienv-python/Cargo.toml riichienv-wasm/Cargo.toml pyproject.toml
git commit -m "chore: bump version to X.Y.Z"
git push
```

--------------------------------

### Mortal MJAI Bot Integration

Source: https://github.com/smly/riichienv/blob/main/README.md

Integrates a Mortal MJAI bot with RiichiEnv for playing matches. Ensure your libriichi.mjai.Bot or equivalent is initialized.

```python
from riichienv import RiichiEnv, Action, GameRule
from model import load_model

class MortalAgent:
    def __init__(self, player_id: int):
        self.player_id = player_id
        # Initialize your libriichi.mjai.Bot or equivalent
        self.model = load_model(player_id, "./mortal_v4.pth")

    def act(self, obs) -> Action:
        resp = None
        for event in obs.new_events():
            resp = self.model.react(event)

        action = obs.select_action_from_mjai(resp)
        assert action is not None, "Mortal must return a legal action"
        return action

env = RiichiEnv(game_mode="4p-red-half", rule=GameRule.default_tenhou())
agents = {pid: MortalAgent(pid) for pid in range(4)}
obs_dict = env.reset()
while not env.done():
    actions = {pid: agents[pid].act(obs) for pid, obs in obs_dict.items()}
    obs_dict = env.step(actions)

print(env.scores(), env.ranks())
```

--------------------------------

### Apply MJAI Event for State Update Only

Source: https://github.com/smly/riichienv/blob/main/README.md

Use `apply_event` when replaying full game logs for training data generation where all events are known and observation timing is managed externally. Observations must be retrieved separately using `get_observation`.

```python
env = RiichiEnv(game_mode="4p-red-half")
env.apply_event({"type": "start_game"})
env.apply_event({"type": "start_kyoku", "bakaze": "E", ...})
env.apply_event({"type": "tsumo", "actor": 0, "pai": "5m"})
# Manually check for actions:
obs = env.get_observation(player_id=0)
if obs.legal_actions():
    ...
```

--------------------------------

### Helper Function: Make Section

Source: https://github.com/smly/riichienv/blob/main/riichienv-ui/player_custom_demo.html

Creates a div element representing a section within the detail view, including a title.

```javascript
function makeSection(title) {
 const sec = document.createElement('div');
 sec.className = 'detail-section';
 const t = document.createElement('div');
 t.className = 'detail-section-title';
 t.textContent = title;
 sec.appendChild(t);
 return sec;
}
```

--------------------------------

### Lint All Rust Code with Features

Source: https://github.com/smly/riichienv/blob/main/docs/DEVELOPMENT_GUIDE.md

Runs Rust linters (clippy) on all targets and features, including Python bindings.

```bash
cargo clippy --all-targets --all-features
```

--------------------------------

### Add riichienv-core to Cargo Project

Source: https://github.com/smly/riichienv/blob/main/riichienv-core/README.md

Use this command to add the riichienv-core crate as a dependency to your Rust project.

```bash
cargo add riichienv-core
```

--------------------------------

### apply_event

Source: https://github.com/smly/riichienv/blob/main/README.md

Applies a given MJAI event dictionary to update the game state. Observations must be fetched separately using `get_observation`. This method is suitable for replaying game logs or when external management of observation timing is required.

```APIDOC
## `apply_event(event)`

### Description
Applies an MJAI event dict to advance the game state. Observations must be retrieved separately via `get_observation(player_id)`.

### Method
`apply_event`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **event** (dict) - Required - An MJAI event dictionary representing a game event.

### Request Example
```python
# Example usage within Python
env.apply_event({"type": "start_game"})
env.apply_event({"type": "start_kyoku", "bakaze": "E", ...})
env.apply_event({"type": "tsumo", "actor": 0, "pai": "5m"})
```

### Response
#### Success Response
None (This method updates state in-place).

#### Response Example
None
```

--------------------------------

### Check Python Wrapper Compilation

Source: https://github.com/smly/riichienv/blob/main/docs/DEVELOPMENT_GUIDE.md

Checks if the riichienv-python crate compiles.

```bash
cargo check -p riichienv-python
```

--------------------------------

### Run Python Type Checker

Source: https://github.com/smly/riichienv/blob/main/docs/DEVELOPMENT_GUIDE.md

Perform type checking on the Python code using `ty check`.

```bash
uv run ty check
```

--------------------------------

### Select Action from MJAI Response

Source: https://github.com/smly/riichienv/blob/main/README.md

Maps an MJAI protocol response to a valid `Action` object within the RiichiEnv environment. This is useful for agents that communicate using the MJAI protocol.

```python
obs.select_action_from_mjai({"type":"dahai","pai":"1m","tsumogiri":False,"actor":0})
```

--------------------------------

### Auto-Selecting First Kyoku

Source: https://github.com/smly/riichienv/blob/main/riichienv-ui/player_custom_demo.html

Automatically selects the first kyoku (round) if there are any summaries available when the UI loads.

```javascript
// Auto-select first kyoku
if (summaries.length > 0) {
 selectKyoku(0);
}
```

--------------------------------

### Helper Function: Make Badge

Source: https://github.com/smly/riichienv/blob/main/riichienv-ui/player_custom_demo.html

Creates a span element with 'badge' class and an additional class for styling, used for displaying tags or labels.

```javascript
function makeBadge(text, cls) {
 const el = document.createElement('span');
 el.className = 'badge ' + cls;
 el.textContent = text;
 return el;
}
```

--------------------------------

### Simulate 4-Player Game with Random Agent

Source: https://github.com/smly/riichienv/blob/main/riichienv-ui/demos/replay_demo.ipynb

Simulates a 4-player game of Riichi Mahjong using a RandomAgent. The game continues until completion, and final scores and ranks are printed.

```python
from riichienv import RiichiEnv
from riichienv.visualizer import GameViewer
from riichienv.agents import RandomAgent


agent = RandomAgent()
env = RiichiEnv(game_mode="4p-red-half")
obs_dict = env.reset()
while not env.done():
    actions = {player_id: agent.act(obs)
               for player_id, obs in obs_dict.items()}
    obs_dict = env.step(actions)

scores, ranks = env.scores(), env.ranks()
print(scores, ranks)
```