Repository navigation
feat(shell): Run several Character Instances at once - #163
Merged
Merged
Conversation
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
force-pushed
the
feat/13-character-instances
branch
from
September 1, 2026 16:50
f6b646d to
aceafb9
Compare
This was referenced Sep 1, 2026
Closed
This was referenced Sep 1, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
Rosterhas held one Engine per Character Instance since #13's core landed, and nothing in the Shell used it.main.rsbuilt a singleEngine, sent a singlePlacement, andsrc/main.jsdrew 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:
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, andAI_BUDDY_CHARACTERstill picks its Character.Per-Instance state that would be visible if shared moved onto
InstanceStatebeside 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; onePointerwould 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, andRoster::spawnnow 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_targetarbitrates 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::Contexthas 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
New tests:
parse_specs(7 cases),press_target(5),starting_positions,out_of_phase,two_instances_of_one_character_do_not_pick_in_lockstep, andnaming_no_instances_asks_for_none_and_a_list_is_read_in_full.scripts/verify-overlay.shpasses unchanged — the frame loop, hit-test pipeline, and grip checks all pass with one Instance, which is the regression guard on the old path. Theframe: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
Paceclocks 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 aponytail:comment; a shared budget wants somewhere to show the spend, which is Tray and settings #18's panel.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.shpasses with it, physics checks included.director::duefires onactivity.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.Closes #13