docs(book): the game host already has the files your site wants (chapter 3 §2b) #12

wtclaude · 2026-09-14T18:11:41Z

wtclaude commented

2026-09-14 18:11:41 +00:00

The kit's whole share of the Asset Bridge: one section in the sidecar chapter, teaching the pattern and re-specifying nothing (docs/link/v8.md §15, §17.13; docs#244). v8.md stays normative and is linked out to, as every chapter does.

Why it earns a section

The problem is general even though our instance of it is not. Most games keep content on the host that a website wants to show — sprites, icons, portraits, localisation tables, map definitions. It is static, it is large, and it changes only when an operator patches the game.

The tempting answer is to make it the operator's problem: export it on a desktop with some third-party tool, upload the result, repeat after every patch. It works once and rots immediately, because nothing reminds anyone to redo it. The better answer costs less than it sounds like — the game host already has those files, and you already have a channel to the game host.

The four notes, all learned expensively

Request/reply, never events. A sidecar that persists and broadcasts every event would write megabytes of sprite into its own store and fan it out to every connected client.
Serve one at a time, and put "busy" in the protocol. A caller that treats busy as flow control rather than failure gets a working import out of it.
Two stages: what exists, then what changed. The common case — a restart that changed nothing — must cost one small round trip.
Version your derivation separately from the protocol. Improving how you read a file changes your bytes while the source file's hash does not.

Plus the operational note that surprises people: do not import on boot.

Base branch

Based on main, not edge — the kit's chapter 5 and the §2a this section follows are on main only, so it has nowhere to sit on edge.

Checks

checkLinks.js (72 links / 16 files), checkChapterPaths.js (37 paths), checkRenameSites.js (32 files), and both script test suites (10 + 11) pass.

AI disclosure

Written with Claude Code (Claude Opus 5); commits carry the Co-Authored-By trailer.

🤖 Generated with Claude Code

https://claude.ai/code/session_016wDDVXWMDz82WqE1i969r4

The kit's whole share of the Asset Bridge: **one section** in the sidecar chapter, teaching the pattern and re-specifying nothing (`docs/link/v8.md` §15, §17.13; docs#244). `v8.md` stays normative and is linked out to, as every chapter does. ## Why it earns a section The problem is general even though our instance of it is not. Most games keep **content on the host** that a website wants to show — sprites, icons, portraits, localisation tables, map definitions. It is static, it is large, and it changes only when an operator patches the game. The tempting answer is to make it the operator's problem: export it on a desktop with some third-party tool, upload the result, repeat after every patch. It works once and rots immediately, because nothing reminds anyone to redo it. The better answer costs less than it sounds like — the game host already has those files, and you already have a channel to the game host. ## The four notes, all learned expensively - **Request/reply, never events.** A sidecar that persists and broadcasts every event would write megabytes of sprite into its own store and fan it out to every connected client. - **Serve one at a time, and put "busy" in the protocol.** A caller that treats busy as flow control rather than failure gets a working import out of it. - **Two stages: what exists, then what changed.** The common case — a restart that changed nothing — must cost one small round trip. - **Version your *derivation* separately from the protocol.** Improving how you read a file changes your bytes while the source file's hash does not. Plus the operational note that surprises people: **do not import on boot.** ## Base branch Based on **`main`, not `edge`** — the kit's chapter 5 and the §2a this section follows are on `main` only, so it has nowhere to sit on `edge`. ## Checks `checkLinks.js` (72 links / 16 files), `checkChapterPaths.js` (37 paths), `checkRenameSites.js` (32 files), and both script test suites (10 + 11) pass. ## AI disclosure Written with Claude Code (Claude Opus 5); commits carry the `Co-Authored-By` trailer. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_016wDDVXWMDz82WqE1i969r4

wtclaude added 1 commit 2026-09-14 18:11:43 +00:00

docs(book): the game host already has the files your site wants (chapter 3 §2b)

PR Checks / prose (pull_request) Successful in 16s

Details

PR Checks / template (pull_request) Successful in 36s

Details

ad37cade6e

The integration kit's share of the Asset Bridge, and the whole of it: one section
in the sidecar chapter, teaching the pattern rather than re-specifying anything.
`docs/link/v8.md` stays normative and is linked out to, as every chapter does.

The problem is general even though our instance of it is not. Most games keep
content on the host that a website wants to show -- sprites, icons, portraits,
localisation tables, map definitions -- and the tempting answer is to make it the
operator's problem: export it on a desktop with a third-party tool, upload the
result, repeat after every patch. It works once and rots immediately.

The four design notes are the ones that cost us real time to learn: content rides
request/reply and never events (a sidecar that persists and broadcasts every
event would write megabytes of sprite into its store and fan it out to every
client); serve one at a time and put "busy" in the protocol so a caller treats it
as flow control; two stages, so the common case -- a restart that changed nothing
-- costs one small round trip; and version your DERIVATION separately from the
protocol, because improving how you read a file changes your bytes while the
file's hash stays put.

Plus the operational note that surprises people: do not import on boot.

Based on `main` rather than `edge` deliberately -- the kit's chapter 5 and the
§2a it follows are on main only, so this section has nowhere to sit on edge.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016wDDVXWMDz82WqE1i969r4

whitlocktech merged commit e852e5574d into main

2026-09-14 22:25:39 +00:00

whitlocktech deleted branch docs/asset-bridge-p9

2026-09-14 22:25:40 +00:00

whitlocktech referenced this issue from a commit

2026-09-14 22:25:43 +00:00

Merge pull request 'docs(book): the game host already has the files your site wants (chapter 3 §2b)' (#12) from docs/asset-bridge-p9 into main

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: RunicGateway/Integration-kit#12