Skip to content

feat(shell): Run several Character Instances at once - #163

Merged
omesser merged 1 commit into
mainfrom
feat/13-character-instances
Sep 1, 2026
Merged

omesser merged 1 commit into
mainfrom
feat/13-character-instances

Conversation

@omesser

@omesser omesser commented Sep 1, 2026 •

Copy link
Copy Markdown
Owner

Why

Roster has held one Engine per Character Instance since #13's core landed, and nothing in the Shell used it. main.rs built a single Engine, sent a single Placement, and src/main.js drew one sprite — so the half of #13 that puts a second buddy on screen did not exist.

What changed

The frame loop ticks every Instance in the Roster and tells each overlay about all of them.

Two decisions were made ahead of the work, both departing from the issue text:

  • N sprites per display overlay, not one window per Instance. The issue asks for "its own overlay window", but per-display overlays are what keep a Character standing on a display seam whole — both overlays draw it and the halves meet. Keeping them preserves the seam, the hit-test, and the fade untouched.
  • The Instance set is settled at launch, by AI_BUDDY_INSTANCES="bmo:One,bmo:Two,nim:Nim". Nothing can ask the user for a name until Tray and settings #18's menu lands. Setting nothing runs the one buddy ai-buddy has always run, and AI_BUDDY_CHARACTER still picks its Character.

Per-Instance state that would be visible if shared moved onto InstanceState beside the Engine: Director and seed, Pointer, wake clocks, and the last rectangle the hit-test used. One Director for two buddies would move them in lockstep; one Pointer would have a double-click on one Summon the other.

What is deliberately shared, once per tick rather than once per buddy: the desktop reading, the window-list poll, the assembled WorldSnapshot, and the hide rules. Art is keyed by Character, so two Instances of one Character encode one copy, and Roster::spawn now borrows the Character rather than cloning every frame of its art per buddy. memory::shared_path() gives the Roster and the MCP server one definition of the Memory file instead of two.

input::press_target arbitrates one cursor across N sprites: the sprite drawn in front wins an overlap, and a buddy already in a gesture keeps the press wherever the cursor goes — #6's rule, extended so a drag cannot pass to a sprite the cursor crossed.

Not done, and not this issue's: runtime spawn and dismiss UI (#18), interaction between buddies (#53), and Memory reaching the Character Prompt — the file is shared, but director::Context has no memory field, so no buddy recites a fact yet. Two acceptance criteria stay open on that: "List Instances and their names" has no surface until #18 or #16, and "a second Instance already knows the user" holds at the file level only.

How to verify

cargo test                      # 330 core + 38 shell, 0 failed
node --test tests/              # 23 pass
cargo clippy --all-targets -- -D warnings
scripts/verify-overlay.sh       # all machine checks pass

New tests: parse_specs (7 cases), press_target (5), starting_positions, out_of_phase, two_instances_of_one_character_do_not_pick_in_lockstep, and naming_no_instances_asks_for_none_and_a_list_is_read_in_full.

scripts/verify-overlay.sh passes unchanged — the frame loop, hit-test pipeline, and grip checks all pass with one Instance, which is the regression guard on the old path. The frame: trace keeps its prefix so the script's regexes still match; the Instance id is appended at the end.

Checked by hand with three Instances (AI_BUDDY_INSTANCES="bmo:One,bmo:Two,nim:Nim"): two Character loads for three Instances, three sprites drawn at three positions, and the three Directors picking different Behaviors on the same round. README steps 24–27 are the manual checklist for what only a human can judge.

Notes

  • A code review of this branch found four real defects, all fixed here: z-order was inverted so bubbles painted over sprites; the starting spread stepped by each Character's own width instead of accumulating, so a narrow Character after a wide one overlapped; the spread arithmetic shipped untested; and the commit subject had no Conventional Commits type.
  • N Instances make N× model calls, on N independent Pace clocks against no shared budget. Per-Instance Directors are what independent Behavior requires, so this is the cost of the feature rather than a defect. Marked with a ponytail: comment; a shared budget wants somewhere to show the spend, which is Tray and settings #18's panel.
  • Each Instance's wake clock starts at a random point inside the interval, drawn from the launch seed through Seeded — now public, so the Shell draws from the same mixer the Director does rather than growing a second one. An even share apiece was the first attempt and is its own kind of mechanical: the same buddies wake in the same order at the same spacing all session. A draw each makes the spacing uneven and different every launch. This also changes the single-Instance case, whose first interval wake was previously always exactly one interval after launch; scripts/verify-overlay.sh passes with it, physics checks included.
  • Buddies still wake together when the desktop itself changes — director::due fires on activity.switched, which every Instance sees. That is a shared event each should react to, so it is deliberately not staggered; only the interval-driven wakes are spread.
  • Still needs a human, per README: that a click really lands underneath, and that typing elsewhere survives a click on a sprite.

Closes #13

The Roster has held one Engine per Instance since #13's core landed and
nothing in the Shell used it. The frame loop now ticks every Instance and
tells each overlay about all of them; the reasoning lives in the comments
on InstanceState, Placement, and press_target.

Which buddies run is settled at launch by AI_BUDDY_INSTANCES, because
nothing can ask for a name until #18's menu exists.
@omesser
omesser force-pushed the feat/13-character-instances branch from f6b646d to aceafb9 Compare September 1, 2026 16:50
@omesser
omesser merged commit be0bf9f into main Sep 1, 2026
2 checks passed
This was referenced Sep 1, 2026
@omesser
omesser deleted the feat/13-character-instances branch September 1, 2026 17:49
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Character Instances

1 participant