Rens Roosloot

Game FS

Volledige gerenderde weergave van gameFS.md.

Laatst gesynchroniseerd: 13 april 2026

Game FS - Cooperative Shared-Control Platformer (Hand-Built MVP)

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

1. Purpose

This document defines the functional behavior for the first playable MVP of the cooperative shared-control platformer described in gameURS.md.

This MVP uses a hand-built level flow to validate the core mechanic: two players controlling one character, and is the basis for an old-school multi-level progression mode.

2. Scope (MVP)

In scope:

  • One playable hand-built side-scrolling level (split into short rooms/chunks) as the first campaign level format
  • Two local players on one keyboard
  • One shared character
  • Shared-control split across two players
  • One control remap event during gameplay
  • Basic interactions:
    • moving block
    • switch
    • moving/lowering platform or bridge
  • Level completion goal (exit)

Out of scope (MVP):

  • Procedural generation
  • Enemies/combat
  • Multiple levels (full campaign content, beyond MVP)
  • Online multiplayer
  • Save system
  • Audio (optional later)

3. Functional Overview

3.1 Core Loop

  1. Players start the level and view control mapping.
  2. Players cooperate to move one character through platform/puzzle obstacles.
  3. Players activate a control remap trigger mid-level.
  4. Players adapt to the new control split.
  5. Players reach the exit and complete the level.

3.2 Success Condition

  • The level is completed when the shared character reaches the exit zone and interact/enter condition is satisfied (or auto-completes on overlap, implementation choice).

3.3 Failure / Reset Behavior

  • The game shall use a small lives system (default: 3 lives).
  • On fail state (e.g. falling out of bounds), one life is consumed and the character respawns at current room checkpoint.
  • Reset is quick (minimal delay).
  • Manual restart shortcut may be provided.
  • If all lives are consumed, the level shall restart from the Level 1 start checkpoint and lives shall be restored to full.
  • This checkpoint-respawn + lives depletion behavior is the intended default for the future hand-built campaign mode.

3.4 Future Campaign Progression Direction (Post-MVP)

  • Levels shall be played sequentially in an old-school progression flow.
  • Completing a level advances to the next hand-built level.
  • Campaign restart may return players to level 1.
  • Failing within a level still returns players to the latest checkpoint while lives remain.
  • On zero lives, restart returns players to the beginning of the campaign (Level 1) with a full lives refill.

4. Game States

The game shall implement these primary states:

  • menu (or start overlay)
  • playing
  • paused (optional for MVP)
  • win

4.1 Start Overlay

The start overlay shall display:

  • game concept summary (“2 players control 1 character”)
  • current control split for both players
  • start instruction (e.g. press key)

4.2 Win State

On completion:

  • show a short success message
  • show replay/restart option
  • optionally show time or attempt count (if implemented)

5. Input and Control Mapping

5.1 Keyboard Inputs

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

5.2 Action Set

MVP action set:

  • moveLeft
  • moveRight
  • jump
  • interactDown (context action and/or crouch/down switch use)

5.3 Split Control Rules

  • Each action is assigned to exactly one player at a time.
  • Players must combine inputs to complete the level.
  • The game shall visually display current assignments.

5.3.1 Initial Mapping (MVP default)

  • Player 1: moveLeft, jump
  • Player 2: moveRight, interactDown

5.3.2 Remapped Mapping (MVP event)

At a defined trigger point, mapping changes to a second configuration.

Recommended remap:

  • Player 1: moveRight, interactDown
  • Player 2: moveLeft, jump

6. Character Movement and Physics (MVP)

6.1 Movement

  • Character moves left/right on ground.
  • Character can jump when grounded.
  • Character is affected by gravity.

6.2 Collision

  • Solid tiles/platforms block movement.
  • Character stands on top surfaces.
  • Character cannot pass through solid walls/floors.

6.3 Down / Interact Behavior

interactDown is context-sensitive:

  • activates nearby switch if in range
  • may crouch or do nothing when no interaction is available (implementation choice)

7. Interactable Objects (MVP)

7.1 Movable Block

  • Block can be pushed horizontally by the character.
  • Block obeys simple gravity.
  • Block can be used as a step to reach higher platforms.
  • Block shall not clip through walls/floors.

7.2 Switch

  • Switch activates when character is in range and interactDown is pressed.
  • Switch changes linked platform/bridge state.
  • Switch state may be:
    • one-way (stays activated), or
    • toggle (on/off)

MVP recommendation:

  • One-way activation for simpler puzzle readability.

7.3 Linked Platform / Bridge

  • Platform/bridge changes state after switch activation (e.g. lowers into reachable position).
  • State change should be visually clear.
  • Transition may be instant or short animated motion.

8. Level Structure (Hand-Built MVP)

The level shall be divided into short segments/rooms for clarity and tuning.

Recommended structure:

8.1 Room 1 - Movement Tutorial

  • Flat ground + small step/ledge
  • Teaches basic cooperation for left/right/jump

8.2 Room 2 - Block Climb

  • One movable block
  • Ledge requiring block placement to climb

8.3 Room 3 - Switch Platform

  • One switch controlling a lowered bridge/platform
  • Requires use of interactDown

8.4 Room 4 - Control Remap Trigger

  • Trigger changes control assignments
  • On-screen overlay briefly explains new controls
  • Short challenge to practice new mapping

8.5 Room 5 - Exit Challenge

  • Simple combined puzzle/platform section
  • Exit door/goal at end

8.6 Initial Campaign Level Progression (Post-MVP Content Plan)

The first campaign set should follow a strict teaching progression:

  • Level 1 introduces only the shared-control movement concept.
  • Each subsequent level introduces one new gameplay element.
  • Earlier mechanics reappear in later levels as combinations.
  • Every level includes at least one fail condition/hazard and uses checkpoint recovery.

8.6.1 Level 1 - Intro / Shared-Control Onboarding

New element:

  • shared-control movement only

Hazard:

  • falling into small pits/gaps

Functional intent:

  • teach cooperation for left/right/jump without introducing block/switch/remap
  • teach checkpoint-respawn through at least one safe fail moment

Recommended segment flow:

  1. safe start + low step
  2. small pits (easy fail/retry)
  3. short platform sequence + one wider gap
  4. short remix + visible exit

8.6.2 Level 2 - Movable Block Introduction

New element:

  • movable block

Hazard:

  • falling, plus positioning mistakes that require retry

Functional intent:

  • teach pushing a block and using it as a step to reach a ledge
  • ensure checkpoint/reset restores block state to avoid softlocks

8.6.3 Level 3 - Switch + Bridge Introduction

New element:

  • switch interaction controlling a bridge/platform

Hazard:

  • falling from bridge/gap sections

Functional intent:

  • teach use of interactDown
  • clearly communicate switch cause/effect and bridge state change
  • retain and rehearse earlier mechanics (jumping and movable block use) inside the lift/switch level so progression builds mastery instead of replacing mechanics

Recommended Level 3 structure intent:

  • safe lift/switch introduction first
  • lift + jump application
  • lift + block application
  • short combo finish (lift + block + jump)

Prototype implementation note (current game branch):

  • Level 3 is implemented as the third playable level in the prototype progression (Level 1 -> Level 2 -> Level 3) and uses one-way switches to lower bridge/lift platforms while reusing jump and block interactions.

8.6.4 Level 4 - Control Remap Introduction

New element:

  • control remap as a core challenge

Hazard:

  • falling, with remap stress as the main difficulty source

Functional intent:

  • introduce remap in a safe zone first
  • place a checkpoint immediately after remap introduction
  • avoid precision platforming immediately after first remap
  • introduce a later-room player key-role swap (WASD/Arrow groups swapped between players) as the level's escalation twist
  • place the key-role swap in a safe zone and keep the first post-swap challenge simple

Recommended Level 4 structure intent:

  • Room 1 warm-up with familiar movement/block behavior
  • Room 2 safe remap trigger + simple remap challenge
  • Room 3 remap practice with one known mechanic (block or lift)
  • Room 4 safe player key-role swap trigger + short practice section
  • Room 5 short combo exit under remap + key-role swap

Prototype implementation note (current game branch):

  • Level 4 is implemented as the fourth playable level in the prototype progression and includes both a one-shot remap trigger and a later one-shot key-role swap trigger, with overlays/toasts and checkpoint placement to keep the difficulty communication-first rather than precision-first.

8.6.5 Level 5 - Combination Level (Block + Switch + Remap)

New element:

  • no brand-new system; this level combines previously introduced mechanics

Hazard:

  • falling + ordering/coordination mistakes

Functional intent:

  • validate player understanding of block, switch/bridge, and remap together
  • use frequent checkpoints to keep challenge fair and communication-focused
  • use a short late-level player key-role swap as part of the final communication test (when present in prototype implementation)

Recommended Level 5 structure intent:

  • Room 1 warm-up refresher (block + jump)
  • Room 2 block + switch/bridge combo
  • Room 3 safe remap + combo
  • Room 4 safe key-role swap + combo
  • Room 5 finale (block + lift + jump to exit)

Prototype implementation note (current game branch):

  • Level 5 is implemented as the fifth playable level in the prototype progression and acts as a first combo "exam" level using block, switch/lift, remap, and key-role swap concepts with checkpoint-based recovery and shared lives continuity.

9. Camera and Presentation (MVP)

  • Side-view 2D camera
  • Camera follows character horizontally
  • Camera motion should prioritize readability (no aggressive effects)
  • Visual style: flat 2D sprites, clear platform/interactable contrast

10. UI Requirements (MVP)

The game shall show:

  • current control assignments for both players
  • current room/checkpoint context (optional)
  • restart hint (optional)

When controls remap:

  • show temporary overlay/banner with new mapping
  • pause gameplay briefly or slow input acceptance during messaging (implementation choice)

11. Checkpoints and Respawn

  • Each room start acts as a checkpoint (recommended)
  • On fail, respawn at latest checkpoint
  • Puzzle state reset behavior:
    • MVP recommendation: reset current room state on respawn

12. Non-Functional Functional Notes (Implementation-Oriented)

  • Must run as a static browser page
  • No backend dependencies
  • Keyboard input handling must support simultaneous key presses from both players
  • Maintain simple deterministic logic for easy tuning/debugging

13. MVP Acceptance Criteria

  • FAC-01: Two players can control one character using keyboard split inputs.
  • FAC-02: Initial control split matches the displayed mapping.
  • FAC-03: Character can move, jump, collide with platforms, and respawn after fail.
  • FAC-04: One movable block puzzle is completable.
  • FAC-05: One switch successfully changes a linked platform/bridge state.
  • FAC-06: A control remap trigger changes action ownership and updates on-screen instructions.
  • FAC-06a: A later key-role swap trigger can swap the raw WASD/Arrow player groups while preserving the current action mapping, and the game indicates the swap on-screen.
  • FAC-07: Players can complete the level and reach a win state.

14. Deferred to Later Iterations

  • Procedural or chunk-based generation
  • Additional interactables (doors, pressure plates, timed switches)
  • Multiple levels and full old-school campaign progression implementation
  • Scoring/time leaderboard (local only)
  • Sound/music
  • Controller support

15. Current Implementation Notes (February 26, 2026)

  • The prototype now supports a file-based campaign pipeline via site/swapbound/assets/game-levels/manifest.json plus per-level JSON files using the editor payload structure { world, music }.
  • Runtime level loading uses manifest + JSON files when hosted over http(s) and falls back to built-in JS level builders when external fetch loading is unavailable (for example via file://).
  • The level editor exports/imports the same { world, music } project JSON format, enabling direct promotion of editor-authored levels into the campaign by adding them to the manifest.
  • Room-based music presets (music.roomPresets for rooms R1-R5) are supported in editor-authored levels and applied by the runtime.
  • Editor and runtime support message triggers that show custom NL/EN on-enter toast messages.
  • remap and keyswap trigger feedback remains active (overlay/toast/audio), while movement freeze interruption is disabled.
  • Respawn/checkpoint restoration reconstructs remap/keyswap progress from checkpoint position (instead of preserving stale runtime state), so reset behavior remains consistent after trigger zones.
  • Blocks are carried by moving platforms (including horizontal motion) when standing on top, enabling transport-and-drop block puzzle setups.
Terug naar home