StarAsh042-ComfyUI_RollingArtist/web/docs/RollingCharacter.md

# Rolling Character

Draws characters at random from a character CSV (default `danbooru_character_001.csv`) and outputs
**one line per character** in the form `character tag, copyright tag, character description`
(comma + newline separated), plus a structured JSON result and the tested count. The node is an output
node, so it runs even when nothing consumes its outputs.

- **Output 1 `prompt`**: one line per character, e.g.
  ```
  hakurei_reimu,touhou,1girl,brown eyes,long hair,
  ganyu_\(genshin_impact\),genshin_impact,1girl,horns
  ```
  **No weights**: you will never see the `(name:weight)` form here. Multiple characters are separated by
  a comma plus a newline: every line ends with a comma except the last one, so flattening the output into
  a single line never glues two characters' tags together
- **Output 2 `characters_json`**: `{"characters": [{"name","copyright","top","count","core_tags"}], "status": "OK"}`
- **Output 3 `tested_count`**: number of character combinations recorded in the current database (as a **string**, so it can be wired straight into a text node)

## Data source and trigger layout

The node reads the `trigger` column by default. Verified across all 34,416 rows, that column is a
**fixed two-segment structure**:

| Segment | Content | Verification |
|---|---|---|
| 1 | Character tag (already escaped, ready to use) | == escaped `character` column: 34,416/34,416 |
| 2 | Copyright tag (e.g. `touhou`) | == escaped `copyright` column: 34,416/34,416 |

The column is fixed to `trigger` (not configurable): it always has the two-segment shape above, so no
column-selection parameter is needed.

## Output format

One line per character, fields joined by a single comma:

```
character tag,copyright tag,character description
```

With "Enable Character Description" turned off it becomes:

```
character tag,copyright tag
```

- **Empty parts are omitted**, so no stray commas appear when a character has no copyright or no description
- The character description (`core_tags`) is **deduplicated within the line** (the source data lists some tags twice)
- Multiple characters are separated by a **comma plus a newline**: every line ends with a comma except the
  last one (a single character carries no trailing comma). The line order is the sampling order

## Parameters

| Parameter | Type / range | Description |
|---|---|---|
| `character_count` | INT 1-10 | Characters generated per run, one line each |
| `character_top_ratio` | FLOAT 0.01-1.0 | Top pool ratio: the first `ceil(candidates × ratio)` rows; candidates = characters left after the work filter |
| `character_top_count` | INT 1-10 | Minimum number of Top-pool characters per run |
| `seed` | INT | Random seed |
| `use_top_priority` | BOOLEAN | Draw from the Top pool first |
| `exclude_characters` | STRING | Exclude list, comma separated |
| `force_include` | STRING | Characters that must appear; names not in the CSV still work but carry no tags |
| `copyright_pick` | COMBO | Work dropdown listing **every work** in the CSV (about 3,460 with the default data, sorted by popularity = the sum of the `count` column, descending); the first entry is `(不限)`. Searchable as you type, case-insensitively |
| `describe_character` | BOOLEAN | Whether to append each character's fixed appearance tags (`core_tags`, i.e. the character description) to its line; on by default |
| `custom_csv_path` | STRING | Custom character CSV path; empty uses `danbooru_character_001.csv` |
| `tested_db_path` | STRING | Records database path; empty uses `rollingcharacter.sqlite` (separate from the artist node) |

This node performs **no weight assignment** (hence no weight parameters), **no exhaustion** (characters
are single tags) and **has no dedup mode parameter** (repeats are avoided with a fixed-rule window, see below).

## Work filter: a single dropdown

- The dropdown lists **every work** in the CSV (about 3,460 with the default data), sorted by
  **popularity**: the `count` column summed over the work's characters, descending. That reflects
  "how popular the work is overall" instead of "how many characters it has"; ties are broken by name
  ascending, so the order is stable and reproducible
- The first entry `(不限)` means no filtering
- It is **searchable as you type**, case-insensitively — typing `a` keeps works starting with a, typing
  `ab` narrows it further
- Both the raw `copyright` form (`fate_(series)`) and the escaped `trigger` form (`fate_\(series\)`) are accepted
- The options come from the **default CSV** (`danbooru_character_001.csv`): pointing `custom_csv_path` at
  another file does not change them
- If nothing is left after filtering the node errors out instead of silently emitting an empty prompt

## Repeat avoidance: no repeat within the last 10 outputs

There is no dedup mode any more; instead a fixed-rule **in-memory window** is used:

- The window holds the **last 10 output records**, where one record = one generation (possibly several characters)
- Before sampling, the window's character names are removed from the candidates, so drawing 1 character ten
  times in a row yields ten different characters; with `character_count=3` it means "no repeat within the
  last 30 characters"
- The window lives **in the node instance's memory**: restarting ComfyUI clears it, and several character
  nodes in one workflow each keep their own
- To clear it from a script, call `node.reset_recent()`; `node.recent_names()` shows the current window
- **When the window covers every candidate** (for example when a very small work is selected), the node
  falls back to allowing repeats and logs a WARNING — it never errors out or gets stuck

## Records database (SQLite)

- The default database lives in the node directory: `rollingcharacter.sqlite`, separate from the artist node
  (records carry a `kind=character` mark, so they never impersonate artist records even in a shared file)
- It only stores the **output history** (for `tested_count` and later inspection); repeat avoidance does
  **not** depend on it, so changing `tested_db_path` does not reset the window
- The default database is cleared on every ComfyUI startup

## Notes

- **About 22% of characters have no character description** (`core_tags` empty); those lines carry only the
  character and copyright tags
- About 10 description tags per character on average, so lines get noticeably longer with many characters
- Character names are unique (no duplicates across 34,416 rows), so a name maps directly to its record
- The weight column in stored records is a `1.0` placeholder (characters carry no weights); it only exists
  to keep record keys distinct