How we built the p5.js cartridge

The runtime asks one question before any of its machinery spins up: is this document a sketch? If so it mounts the container instead of a 3D scene. Because that is the whole integration, every existing surface - the store, the battle wizard, the rooms, the editor preview - opens sketches without having changed. The framed cartridge made this argument first; the sketch inherited it for free.

A sketch wakes up with window.xp already there: a roster with join and leave, an avatar that broadcasts itself ten times a second and arrives smoothed on every other screen, one input axis fed by arrows, WASD or a thumbstick, named buttons that fire as triggers for every player, shared objects with a claim - the ball rule - and the document’s flow driven by the platform with a round strip drawn over the canvas.

The point of the surface is what an author never writes: netcode. Setting xp.avatar.x in draw() is the whole of multiplayer movement. A live scoreboard is one line, because the avatar carries a free data object that syncs with it.

The container talks to the platform through postMessage and nothing else. Every message crossing outward is read through one narrow protocol - shapes checked, strings cut to length, payloads size-capped, sends rate-limited - and all of it on the platform’s side, because the other side is the code being limited. A hacked sketch can lie about its own game; it cannot spend the room’s bandwidth or another player’s trust.

The unit tests all passed and the first real two-browser run failed four checks of seven. The wire’s envelope carries the sender inside the payload - that is also how a client drops its own echo - and the stage sent bare payloads, so ball claims travelled while avatars and button presses arrived from nobody. The fix was one field; finding it required two actual signed-in browsers in one actual room.

The same probe caught the editor’s code pane editing text three screens below the caret, because its two stacked layers wrapped long lines differently. The cure was to stop wrapping entirely, like every code editor.

The container’s content policy allows exactly three asset directories, so the wrapper turns them into loaders: pack pictures as stable handles, shipped sounds as take-cycling players, and pack models through a small glTF reader - mesh, transform, base-colour texture - because p5 reads OBJ and STL and the packs ship glTF. A player’s own peep can stand in a sketch, textured, from one call.

One measured surprise is worth writing down: p5 2.x returns Promises from its loaders where 1.x returned images. Everything the wrapper hands out is therefore a handle - check ready, draw image - so no sketch ever has to know which p5 is underneath.