# Ok Ww Characters

> Create, modify, review, and test Wuthering Waves character automation classes under src/char in ok-wuthering-waves. Use when Codex needs to add a new character, update a character rotation, map character skill descriptions into BaseChar logic, register CharFactory entries, reason about Labels feature names, or support English and Chinese combat terminology such as echo, resonance, forte, liberation, click, and heavy.

- Skill: `ok-oldking/ok-ww-characters` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add ok-oldking/ok-ww-characters`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ok-oldking/ok-ww-characters/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: ok-oldking (https://skillmd.com/u/ok-oldking)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ok-oldking/ok-ww-characters

---


# OK-WW Characters

## Overview

Use this skill for character combat logic in `src/char`. A character implementation translates game mechanics from a skill-description page or user notes into a `BaseChar` subclass, then registers the class in `src/char/CharFactory.py`.

Read `references/character-patterns.md` for the detailed API, templates, and validation checklist.

## Workflow

1. Inspect nearby character classes before editing.
   Prefer recent characters with similar mechanics, for example aerial/stance characters, healer classes, liberation stance characters, or forte-heavy characters.
2. Read the provided character description page if one is given.
   Extract only automation-relevant mechanics: normal attack chain, resonance skill behavior, forte trigger, liberation state, echo timing, intro/outro interactions, cooldowns, and required UI indicators.
3. Map terminology consistently:
   - `echo` = 声骸 / 声骸技能
   - `resonance` = 共鸣技能
   - `forte` = 共鸣回路
   - `liberation` = 共鸣解放
   - `click` = 普通攻击
   - `heavy` = 重击
4. Create or update `src/char/<CharacterName>.py`.
   Implement a `BaseChar` or `Healer` subclass with `do_perform()` as the primary rotation.
5. Register the character in `src/char/CharFactory.py`.
   Add the import and `_char_dict_raw` entry with `Labels.<char_label>`, cooldowns, `liberation_cd` if non-default, and `ring_index`.
6. Treat visual feature labels as developer-owned.
   If the rotation needs new image/template detections, name the expected `Labels` entries and where they are used, but do not fabricate asset annotations. The developer must add the feature in `Labels` and template data.
7. Add or update tests only when screenshots exist or the change touches recognition/availability logic.
   Use existing `tests/TestChar.py` patterns.

## Bilingual Rules

- Answer in the user's language. For mixed English/Chinese requests, include both key game terms when it helps.
- Keep Python method names and local variables in English unless the surrounding code already uses another style.
- Use Chinese comments only when they explain a game mechanic more clearly than English; keep comments sparse.
- Preserve exact `Labels` enum names used by assets and annotations.

## Character Description Pages

When a page such as `https://ww.nanoka.cc/character/1210/` is provided, use it as a mechanics reference, not as code truth. Convert the page's combat sections into automation decisions:

- Which action starts the damage loop?
- Which UI indicator proves a stance, forte, enhanced skill, or special attack is ready?
- Which action consumes the state?
- Should the character stay on field, switch after one action, or fast-switch on intro?
- Does liberation cause animation freeze or a long alternate state?

Always verify the implementation against this repo's helpers and available labels.

## Essential Rules

- Do not add a character class without registering it in `CharFactory.py`.
- Do not invent `Labels` feature names silently. If a new feature is required, document the intended label and tell the developer it must be added.
- Use `self.time_elapsed_accounting_for_freeze(...)` for rotation timing when liberation or intro animation can freeze time.
- Prefer `click_resonance`, `click_liberation`, `click_echo`, `heavy_attack`, `continues_normal_attack`, `heavy_click_forte`, `is_forte_full`, `has_long_action`, and `f_break` over raw key calls.
- Keep loops bounded by timeouts and call `self.task.next_frame()` or `self.sleep(...)` inside polling loops.
- Use `Priority` overrides only when switching behavior truly depends on intro, cooldown, healer timing, or a long buff window.