Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 10 additions & 6 deletions DESIGN.md
Original file line number Diff line number Diff line change
Expand Up @@ -356,11 +356,15 @@ to being called spyware.
Physics runs in a single coordinate space, the one every display shares.
Reconciling per-display physics would be considerably harder.

The overlay window is the exception, and not by choice: macOS gives each display
its own Space and draws a window spanning two of them on only one, so the window
covers a single display and the frame loop moves it to whichever display the
sprite reaches. A sprite straddling the boundary is clipped, which one overlay
per display would fix and nothing else will.
The overlays are per display, and not by choice: macOS gives each display its
own Space and draws a window spanning two of them on only one, so a window sized
to the union is invisible everywhere but the display it belongs to. Every
display therefore gets its own overlay covering it, and every overlay is told
where the sprite is, in its own coordinates. A sprite straddling a boundary is
drawn by both and clipped by each to its own half, so the halves meet at the
seam. One code path builds and configures an overlay, because click-through,
window level, Spaces membership and hide rules have to be identical across all
of them.

Two real problems to budget for: differing backing scale factors between
displays, and gaps between non-aligned displays. Clamp to the union of visible
Expand Down Expand Up @@ -474,5 +478,5 @@ records it.
| 20 | Memory | One shared plaintext Markdown file the user owns; chat history session-scoped |
| 21 | No Harness attached | Fully charming — full Spatial Layer, chat shows a connect nudge |
| 23 | Art | True pixel art, integer nearest-neighbour — [ADR-0006](./docs/adr/0006-pixel-art-integer-scaling.md) |
| 24 | Displays | Overlay covers one display and follows the sprite; physics spans them all |
| 24 | Displays | One overlay per display, each covering it; physics spans them all |
| 25 | Release staging | v1 is charm, chat, Memory, and Harness attach; voice and Ambient Capture deferred |
36 changes: 30 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -114,9 +114,10 @@ it when the overlay, the platform layer or the frame loop changes.
scripts/verify-overlay.sh # or --keep to leave the app running
```

It checks that exactly one overlay window exists at floating level, that its
bounds match one whole display — the one the Character is on — and that the app
is an accessory with no Dock tile or switcher entry.
It checks that there is one overlay window per display, that every one of them
is on screen at floating level, that each display is covered whole by one of
them and none of them covers anything else, and that the app is an accessory
with no Dock tile or switcher entry.

Then it checks the frame loop against a real desktop. It opens a plain window of
its own below where the sprite starts, so the sprite has a Perch to aim at, and
Expand All @@ -136,9 +137,13 @@ Keep hands off the mouse while it runs.

For a live view of what the app is deciding, set `AI_BUDDY_TRACE_HITTEST=1` for
the click-through decision and `AI_BUDDY_TRACE_FRAMES=1` for the Engine's
frames — state, position and animation, once per tick. The first line or two of
the hit-test trace are emitted before the window frame settles and report a
stale origin; read the later ones.
frames — state, position and animation, once per tick. Both trace in the point
space every display shares, so the positions they report are comparable with
what the window server says about any display.

There is one overlay per display and every one of them is told where the
sprite is, so the trace is one line per tick rather than one per overlay. Which
overlay the cursor is on is on the hit-test line.

**A human** is still needed for the last step, because only the window server
can answer it. Run the app, then confirm:
Expand Down Expand Up @@ -195,6 +200,25 @@ can answer it. Run the app, then confirm:
goes where your hand goes. Let go and it settles back onto the Dock's top
edge, fully visible.

The last three need a second display, and only a window server can answer them:

13. **A Character on a seam is whole.** Drag the sprite slowly across the
boundary between two displays and hold it there, half on each. Both halves
are drawn, and they meet — no gap between them, nothing drawn twice, and
the art is not doubled or offset at the seam. Watch them while your hand is
still moving, not only once it stops: each overlay interpolates between the
Engine's ticks on its own clock, so a moving sprite is the only thing that
can catch two overlays disagreeing about where it is. Two displays with
different scale factors or refresh rates is the case worth doing this on.
14. **Either half can be clicked.** With the sprite straddling, click the half
on each display in turn. Both pick it up, and clicking beside it on either
display still reaches whatever is underneath.
15. **A display can come and go.** With the app running, unplug a display, or
turn one off in System Settings > Displays. The sprite carries on, and the
remaining display still passes clicks through where the sprite is not.
Plug it back in: the sprite can be dragged onto it again within a second
or so, without restarting the app.

The sprite starts in the middle of the first display and goes wherever gravity
and your windows take it from there, or wherever you put it. To watch it fall
without touching it, move or close the window it is sitting on.
Expand Down
Loading
Loading