Game DS - Cooperative Shared-Control Platformer (Hand-Built MVP Design)

Version: 1.0
Date: March 8, 2026
Author: Rens Roosloot / Codex collaboration

1. Purpose

This document defines the design specification for the first implementation of the cooperative shared-control platformer MVP described in gameURS.md and gameFS.md, and notes the intended extension path toward a hand-built multi-level campaign.

The design prioritizes:

• fast implementation
• low complexity
• static-site compatibility
• clear separation of game systems for iteration

2. Implementation Strategy (MVP)

2.1 Delivery Model

• Single static HTML page under site/ (exact filename to be decided later)
• Client-side JavaScript only
• No backend, no external runtime dependencies

2.2 Rendering Approach

Recommended MVP approach:

• HTML5 <canvas> 2D rendering

Reason:

• good fit for platformer movement/collision rendering
• easier camera and sprite layering than DOM-based rendering
• small runtime surface, no framework required

3. High-Level Architecture

The game loop is split into these subsystems:

1. Input System
2. Control Split Mapper
3. Game State Manager
4. Level / Room Data
5. Physics + Collision
6. Interaction System
7. Checkpoint / Respawn System
8. Camera System
9. Renderer / UI Overlay

4. Main Runtime Flow

Per frame (requestAnimationFrame):

1. Read keyboard state
2. Convert key state to player action intents
3. Apply current control split mapping to produce shared-character commands
4. Update game state (playing/win/etc.)
5. Update character physics and collisions
6. Update interactables (block/switch/platform)
7. Resolve room triggers (checkpoint/remap/keyswap/exit)
8. Update camera
9. Render world and UI overlays

5. State Model

5.1 Global Game State

Proposed shape:

• mode: start | playing | win | paused (paused optional)
• timeMs
• lives
• maxLives
• attemptCount (optional)
• currentRoomIndex
• currentControlMappingId
• showRemapOverlay
• currentLevelIndex (future campaign mode)
• campaignMode / progression state (future campaign mode)

5.2 Shared Character State

Proposed fields:

• x, y
• vx, vy
• w, h
• grounded
• facing
• interactionRange
• spawnX, spawnY (or checkpoint reference)

5.3 Room State

Each room tracks:

• static solids/platform layout
• interactables
• triggers
• room-local reset state snapshot

6. Input System Design

6.1 Raw Input Tracking

Use a keyboard state map:

• pressed[key] = true/false

Track both:

• held state (movement)
• edge-trigger state (justPressed) for jump/interact/menu actions

6.2 Player Key Groups

• Player 1 keys: W, A, S, D
• Player 2 keys: ArrowUp, ArrowLeft, ArrowDown, ArrowRight

Normalize to logical player intents:

• p1.up, p1.left, p1.down, p1.right
• p2.up, p2.left, p2.down, p2.right

7. Control Split Mapping Design

7.1 Mapping Abstraction

Map actions to (player, directionKey) instead of hardcoding.

Example mapping object:

• moveLeft -> p1.left
• jump -> p1.up
• moveRight -> p2.right
• interactDown -> p2.down

7.2 Remap Trigger

When character overlaps a remap trigger:

• set currentControlMappingId to next mapping
• show temporary remap overlay
• optional brief freeze (e.g. 300-700ms) to reduce confusion

7.2b Player Key-Role Swap Trigger (Level 4 escalation)

When character overlaps a key-role swap trigger:

• toggle or set a boolean inputSwap state
• swap raw player intent groups before action mapping (p1 intents <-> p2 intents)
• keep current action mapping object active (so the twist is "who owns the keys", not "which action set exists")
• show a temporary keyswap overlay/toast
• optional brief freeze (similar to remap)

7.3 UI Coupling

Control mapping display shall read directly from the active mapping object (single source of truth).

8. Level / Room Data Design (Hand-Built)

8.1 Room-Based Structure

Use a small array of hand-authored rooms.

Each room contains:

• dimensions
• static colliders/platforms
• decorative tiles (optional)
• interactables
• triggers
• checkpoint spawn

8.2 Coordinate System

Use world coordinates in pixels.

Recommended MVP convention:

• top-left origin (0,0)
• +x right
• +y down

8.3 Static Geometry Representation

For MVP simplicity:

• axis-aligned rectangles (AABB) for floors/walls/platforms

This keeps collision logic simple and robust.

8.4 Room Connectivity

Rooms can be implemented as:

• one continuous world with labeled zones, or
• separate room loads with transitions

MVP recommendation:

• one continuous world divided into room zones

Reason:

• simpler camera + persistent block/platform state
• fewer transition edge cases

8.5 Campaign Level Data Progression (Initial Levels 1-5)

The first campaign set should be represented as a sequence of hand-built levels, each with explicit metadata for:

• levelId
• levelName
• introducedMechanic
• hazardType
• checkpoint locations
• room/segment definitions

Recommended progression metadata (initial plan):

• Level 1: introducedMechanic = sharedControlCore, hazardType = pits
• Level 2: introducedMechanic = movableBlock, hazardType = pits
• Level 3: introducedMechanic = switchBridge, hazardType = pits
• Level 4: introducedMechanic = remapPlusKeyRoleSwap, hazardType = pits
• Level 5: introducedMechanic = combo, hazardType = pits

Design implication:

• The level loader should support campaign ordering independently from room geometry, so content can scale from one prototype level to a multi-level campaign without redesigning the runtime loop.

Prototype implementation note:

• The prototype runtime currently supports explicit level builders for at least Level 1, Level 2, and Level 3, with exit-trigger progression between levels and persistent lives across level transitions.
• The prototype runtime on the game branch now supports explicit level builders for Level 1 through Level 5, including a Level 4 keyswap trigger (inputSwap) and a Level 5 combo level that combines block, switch/lift, remap, and key-role swap concepts.

9. Physics and Collision Design

9.1 Physics (MVP)

Use simple arcade physics:

• horizontal acceleration or direct speed set
• gravity
• jump impulse
• max fall speed (optional)

9.2 Collision Resolution

Recommended order:

1. move on X axis, resolve X collisions
2. move on Y axis, resolve Y collisions
3. update grounded flag

This reduces corner-case complexity for an MVP.

9.3 Jump Rules

• Jump only when grounded
• Optional coyote time/jump buffer deferred unless needed for feel

10. Interaction System Design

10.1 Interaction Detection

Character can interact with nearest eligible object within range when interactDown is pressed.

Priority order (MVP suggestion):

1. switch
2. exit
3. other future interactables

10.2 Movable Block

Block entity fields:

• x, y, w, h
• vx, vy
• movable = true

Behavior:

• pushed by character horizontal collision intent
• affected by gravity
• collides with static solids
• may optionally collide with linked platform if platform is solid

10.3 Switch and Linked Platform

Switch entity fields:

• id
• x, y, w, h
• activated
• targetId

Linked platform fields:

• id
• x, y, w, h
• startY, endY (or raised/lowered positions)
• optional startX, endX for horizontal/diagonal movement paths in the prototype editor/runtime integration
• state
• solid

Behavior:

• switch activation updates linked platform state
• platform may animate toward target position (vertical or diagonal path in current prototype runtime when x0/x1/targetX are present)

11. Trigger System Design

Trigger rectangles in room/world data:

• checkpoint
• remap
• keyswap
• exit
• hazard/fall reset (optional)

Each trigger includes:

• bounds
• type
• consumed flag (for one-shot remap overlays/checkpoints)
• payload (e.g. mapping id, checkpoint id, keyswap target boolean)

12. Checkpoint and Reset Design

12.1 Checkpoints

Checkpoint stores:

• character spawn position
• current room/zone id

12.2 Room State Reset

On respawn:

• consume one life (for fail-triggered respawn)
• reset character to latest checkpoint
• reset current room puzzle objects to initial room snapshot

Snapshot approach for MVP:

• keep initial serialized state for room entities
• deep-clone on reset

12.3 Campaign-Oriented Failure Policy (Planned)

• In the planned hand-built multi-level campaign mode, failure shall respawn at the latest checkpoint within the current level while lives remain.
• When lives are depleted, campaign progression resets to Level 1 start and lives are restored to full.

13. Camera Design

13.1 Camera Behavior

• side-follow camera centered near character
• horizontal follow stronger than vertical
• clamp to world bounds

13.2 Stability

• use mild smoothing only if needed
• prioritize readability over cinematic motion

14. Rendering and Visual Design

14.1 Layers (MVP)

• background color / simple gradient
• platforms/solids
• interactables (block, switch, platform)
• character sprite
• trigger feedback (debug optional)
• UI overlays

14.2 Sprite Style

• flat, readable shapes
• minimal animation frames
• consistent contrast for interactables

14.3 UI Overlay Elements

• control mapping panel (Player 1 / Player 2 assignments)
• remap notification banner
• start overlay
• win overlay

15. Data-Driven Content Design (Future-Proofing)

Even in hand-built MVP, define rooms as data objects rather than hardcoded logic.

Benefits:

• easier tuning
• easier transition to chunk-based generation later
• simpler testing of control-remap combinations

16. Performance and Browser Constraints

• Target desktop browsers first
• Keep update/render logic lightweight (single canvas, simple AABB collision)
• Avoid allocations in the main loop where practical
• No third-party game engine for MVP

17. Debug and Tuning Hooks (Recommended)

Optional debug toggles (developer-only):

• show collision boxes
• show triggers
• show current room bounds
• show current mapping id
• restart room / restart level hotkeys

These can significantly speed up iteration during mechanic tuning.

18. MVP Build Sequence (Implementation Order)

Recommended coding order:

1. Canvas setup + game loop
2. Input tracking
3. Character movement + gravity + collisions on simple platforms
4. Room data format + continuous level layout
5. Control split mapping + on-screen mapping UI
6. Checkpoints and respawn
7. Movable block
8. Switch + linked platform
9. Remap trigger + overlay
10. Exit + win state
11. Visual polish
12. (Later) multi-level campaign progression state + level transitions

19. Design Risks and Mitigations

19.1 Risk: Shared-control mechanic feels frustrating

Mitigation:

• short level
• low difficulty
• clear control display
• one remap only in MVP

19.2 Risk: Keyboard ghosting on some keyboards

Mitigation:

• choose tolerant key combinations
• avoid high-frequency simultaneous precision inputs
• test on multiple keyboards if possible

19.3 Risk: Puzzle reset state bugs

Mitigation:

• room-local state snapshots
• deterministic reset path
• keep interactables minimal in MVP

20. Traceability to gameFS.md

• FS control split requirements -> Sections 6, 7, 14
• FS movement/physics/collision -> Sections 9, 10
• FS interactables -> Sections 10, 11
• FS room structure -> Section 8
• FS checkpoints/respawn -> Section 12
• FS UI communication -> Section 14

21. Current Implementation Addendum (February 26, 2026)

21.1 External Level Asset Pipeline

• The runtime supports a manifest-driven level pipeline:
  • site/swapbound/assets/game-levels/manifest.json
  • per-level JSON files (level-XX.json)
• Each level file uses the same project payload format as the editor:
  • { "world": { ... }, "music": { ... } }
• Runtime behavior:
  • http(s) / localhost: load manifest + JSON via fetch
  • file://: fallback to built-in JS level builders when fetch is unavailable

21.2 Editor-to-Runtime Compatibility Contract

• The level editor import/export/test payload is the runtime contract for external levels.
• world contains geometry/interactables/triggers.
• music.roomPresets contains room-based preset names (R1-R5) for room music switching.
• Backward compatibility is maintained for world-only JSON payloads by normalizing missing music.

21.3 Trigger Runtime Behavior (Current)

• Trigger types in active use: checkpoint, remap, keyswap, message, exit.
• remap and keyswap apply gameplay effect + feedback overlays/toasts/audio without movement freeze.
• Respawn rebuilds remap/keyswap progress from checkpoint position by replaying trigger state up to the checkpoint location/room.
• message trigger supports textNl / textEn and optional one-shot behavior (once, default true).

21.4 Physics Addendum

• Blocks are carried by moving platforms using platform frame-delta carry logic when standing on top (horizontal and vertical movement).
• Blocks can rest on the player head and are pushed upward if the player jumps into them and upward space is available (pragmatic non-rigidbody behavior).