GameBlocks — Architecture Overview

flowchart TD
    Dev["Developer\nor AI Agent"] --> Task["3D game prototype task\nreceived"]
    Task --> Trigger["Skill auto-triggered\nor /gameblocks invoked"]
    Trigger --> SkillCtx["SKILL.md injected\ninto agent context"]
    SkillCtx --> Browse["Agent reads summary.md\nbrowse module catalog"]
    Browse --> Select["Select modules\nmatching game type"]
    Select --> Strategy{"Reuse\nstrategy?"}
    Strategy -->|"full match"| CopyUnchanged["Copy module unchanged\npreserve import paths"]
    Strategy -->|"partial match"| Modify["Modify existing\nimplementation"]
    Strategy -->|"no match"| Derive["Derive from scratch\nusing WorldBasis as anchor"]
    CopyUnchanged --> Docs["Create gameblocks_usage.md\nrecord choices and mods"]
    Modify --> Docs
    Derive --> Docs
    Docs --> Proto["Browser 3D Game\nThree.js + Rapier3D"]
          

flowchart LR
    Repo["GameBlocks repo\ncloned locally"] --> Install["cp -R gameblocks/.\n~/.claude/skills/gameblocks/\nor ~/.codex/skills/gameblocks/"]
    Install --> Restart["Restart agent app\n(optional)"]
    Restart --> Ready["Skill available"]
    Ready --> ManualCmd["/gameblocks\nor $gameblocks\nmanual invocation"]
    Ready --> AutoLoad["Agent auto-loads\nwhen task description matches"]
    ManualCmd --> SkillFile["SKILL.md loaded\ninto agent context window"]
    AutoLoad --> SkillFile
          

flowchart TD
    SkillFile["SKILL.md in context\nPrimary directive: use GameBlocks\nbefore inventing from scratch"] --> ReadSummary["Read summary.md\nidentify candidate modules"]
    ReadSummary --> WorldBasisCheck["WorldBasis.js is\ncoordinate authority\nconsult for ALL spatial logic"]
    WorldBasisCheck --> ModuleLoop["For each game system needed"]
    ModuleLoop --> Found{"Module\nexists?"}
    Found -->|"Yes — fully fits"| CopyDirect["Copy unchanged\npreserve dir structure"]
    Found -->|"Yes — partial"| AdaptMod["Modify existing code\ndo not rebuild from scratch"]
    Found -->|"No"| NewCode["Write new code\nanchor to WorldBasis types"]
    CopyDirect --> UsageDoc["gameblocks_usage.md\nmodule + purpose +\nreuse status + mods"]
    AdaptMod --> UsageDoc
    NewCode --> UsageDoc
    UsageDoc --> Integrate["Integrate into\ngame prototype"]
          

flowchart TD
    Math["Math\nWorldBasis · VectorUtils\nScalarUtils · RandomUtils · TimeUtils"]
    Math --> Motion["Actor Motion\n16 modules\nCharacter · Vehicle · Aircraft · Snake"]
    Math --> Camera["Camera\n5 modules\nBaseCameraRig · FP · Follow · LookOffset"]
    Math --> Behavior["Behavior\n6 modules\nPathPlanner · Navigator · Avoidance\nCombatDirector · WaypointDriver"]
    Motion --> Gameplay["Gameplay\n8 modules\nCombatPlay · FlightPlay · RacePlay\nSnakePlay · WaveSpawnDirector"]
    Behavior --> Gameplay
    UI["User Interface\n8 modules\nDomHudRenderer · Minimap\nNotificationQueue · SettingsStore"]
    Gameplay --> World["World\n18 modules\nEnvironments · Objects · Factories · VFX"]
    Camera --> World
    UI --> World
    World --> Output["Rendered Browser Game\nThree.js WebGLRenderer"]
          

flowchart TD
    Input["Raw Input\nleft · right · up · down\nforward · backward · sprint · jump"]
    Input --> WB["WorldBasis.controlSignal()\nmap directional tokens to\nsigned scalar magnitudes"]
    WB --> Base["BaseCharacterMotionController\nposition · velocity · yaw · pitch\nwalkSpeed · jumpVelocity · gravity\naccelerationLag · decelerationLag"]
    Base --> HeadRel["HeadingRelativeCharacterMotionController\nmovement relative to facing yaw\nfirst-person strafe style"]
    Base --> WorldCard["WorldCardinalCharacterMotionController\nmovement in world X/Z axes\ntop-down style"]
    Base --> WorldTarget["WorldTargetCharacterMotionController\nmove toward 3D click target\nRTS / isometric style"]
    Base --> MouseLook["MouseLookCharacterMotionController\nmouse delta drives yaw+pitch\nFPS camera coupling"]
    HeadRel --> KinBatch
    WorldCard --> KinBatch
    WorldTarget --> KinBatch
    MouseLook --> KinBatch
    KinBatch["KinematicBatchResolver\nsubmit to Rapier character controller\nread back corrected position\nhandle slope/step/slope limits"]
    KinBatch --> Pose["Character Pose\nfinal position + quaternion\nfor scene graph"]
    Pose --> VehicleLayer["Ground Vehicle Controllers\nArcadeCarMotionController\nDynamicCarMotionController\nDriftingPlugin"]
    Pose --> AircraftLayer["Aircraft Controllers\nAirplaneMotionController\nAirplaneModelController"]
    Pose --> SpecialLayer["Special Controllers\nSnakeMotionController\nPlateTiltController\nGeneralVehicleMotionController"]
          

flowchart LR
    Grid["GridPathPlanner\nA-star on discrete grid\nreturns waypoint list"]
    Grid --> WP["Waypoint sequence\nworld-space positions"]
    WP --> WaypointDriver["WaypointDriver\nadvance index on arrival\ntrigger callbacks"]
    WP --> Progress["WaypointProgressTracker\ntrack lap / progress fraction\nused by race mode"]
    WaypointDriver --> Navigator["AgentPathNavigator\nflattens to planar plane\narrival deceleration\nreturns direction + desiredSpeed"]
    Navigator --> Avoidance["NearbyAvoidanceSteering\nquery nearby agents\nsteer around neighbours"]
    Avoidance --> Intent["Movement intent\ndirection · desiredSpeed"]
    CombatDir["CombatBehaviorDirector\ncombat state machine\npursue / attack / retreat\nwhen to fire weapon"]
    CombatDir --> Intent
    Intent --> MotionCtrl["Motion Controller\ncommitMovement(intent)"]
          

stateDiagram-v2
    [*] --> WAITING : initial
    WAITING --> WAITING : addPlayer() registers combatants
    WAITING --> STARTED : startGame()
    STARTED --> STARTED : damage(id, amount)\nheal(id, amount)\naddArmor(id, amount)
    STARTED --> STARTED : step() drains event queue\nemits PLAYER_KILLED events
    STARTED --> FINISHED : step() detects\nsingle team alive\nemits COMBAT_FINISHED
    FINISHED --> WAITING : reset() restores\ndefault stats
          

flowchart TD
    GameplayLayer["Gameplay Layer\nOrchestrates rules, tracks state, emits events"]
    GameplayLayer --> CombatPlay["CombatPlay\nhealth · armor · teams\nkill events · WAITING/STARTED/FINISHED"]
    GameplayLayer --> FlightPlay["FlightPlay\naltitude · speed envelope\nstall · crash detection"]
    GameplayLayer --> RacePlay["RaceCheckpointLapPlay\ncheckpoint sequence\nlap counting · finish line"]
    GameplayLayer --> SnakePlay["SnakePlay\ngrid segments · growth\ncollision with self or wall"]
    GameplayLayer --> WaveDir["WaveSpawnDirector\nspawn enemies in waves\ndelay between waves\nescalating difficulty"]
    WaveDir --> SpawnArea["SpawnAreaSampler\nnon-overlapping random\nspawn positions"]
    CombatPlay --> WeaponSys["ProjectileWeaponSystem\ncooldown · ammo · fire\nrecoil model"]
    WeaponSys --> ProjMgr["ProjectileManager\npool + lifetime\ncollision check"]
    ProjMgr --> AimRes["AimResolver\nauto-aim angle\nlead calculation"]
          

flowchart TD
    ActorPose["Actor Pose\nposition · quaternion · forward"]
    ActorPose --> Base["BaseCameraRig\nposition · lookAt · forward/right/up\nrotationMode: lookAt or frame\nsmoothVector() exponential lag"]
    Base --> FP["FirstPersonCameraRig\nattach to actor head bone\noffset by eye height\npitch-clamped"]
    Base --> PosFollow["PositionFollowCameraRig\nfollow actor position\noffset above + behind\nlookAt actor"]
    Base --> PoseFollow["PoseFollowCameraRig\nfollow position AND orientation\nfor vehicle cockpit views"]
    Base --> LookOffset["LookOffsetCameraRig\noffset the lookAt point\nfor over-shoulder style"]
    FP --> ApplyFn["applyToCamera()\nwrite to THREE.Camera\nposition + quaternion"]
    PosFollow --> ApplyFn
    PoseFollow --> ApplyFn
    LookOffset --> ApplyFn
    ApplyFn --> ThreeCam["THREE.PerspectiveCamera\nused by WebGLRenderer"]
          

flowchart LR
    Env["Environment builders"]
    Env --> Arena["ArenaEnvironment\nground · grid · walls\ncylindrical pillars · ramps\nRapier static bodies"]
    Env --> Natural["NaturalEnvironment\nterrain mesh · sky\nplant placement"]
    Env --> Race["RaceTrackEnvironment\nclosed track geometry\ncheckpoint triggers"]
    Env --> Board["BoardEnvironment\ngrid-aligned flat tiles\nfor strategy/puzzle games"]
    Natural --> Terrain["TerrainMeshFactory\nheightmap geometry\nTerrainSampler for height queries\nWorldBoundsColliderFactory"]
    Arena --> Spawn["SpawnAreaSampler\ntest clearance via\nisPlanarPointBlockedByGeometry()\nnon-overlapping spawn set"]
    Natural --> Spawn

    Factories["Visual Factories"]
    Factories --> CarVF["CarVisualFactory\nboxes for body + wheels"]
    Factories --> AirVF["AirplaneVisualFactory\nwings + fuselage geometry"]
    Factories --> ProjVF["ProjectileVisualFactory\nsmall sphere / capsule"]
    Factories --> PlantVF["PlantVisualFactory\nbillboard or simple mesh"]

    WorldObjects["World Objects"]
    WorldObjects --> Pickup["PickupObject\nmesh + trigger zone\ncollect on overlap"]
    WorldObjects --> Projectile["ProjectileObject\nlifetime · velocity\ncollision response"]
    WorldObjects --> FpsVM["FpsWeaponViewModel\nlocal weapon mesh\nbob + sway animation"]
    WorldObjects --> HealthBar["HealthBarView\nbillboard sprite\nscales with HP ratio"]

    VFX["Visual Effects"]
    VFX --> JetFlame["JetFlame\nparticle emitter\nthrust-proportional"]
    VFX --> TireMark["VehicleTireMarkRenderer\ndecal strips on ground"]
    VFX --> WeaponFX["WeaponEffectsSystem\nmuzzle flash · hit sparks"]
    VFX --> ClickFX["GroundClickIndicator\ncircle on click target"]
          

flowchart LR
    RAF["requestAnimationFrame\ndelta time computed"] --> Input["Input Handler\nkeyboard · mouse · gamepad\ncollect pressed keys + axes"]
    Input --> MotionStep["Motion Controllers\nstep(input, delta)\nvelocity integration\njump / gravity / sprint"]
    MotionStep --> RapierStep["Rapier Physics\nworld.step()\ncollider correction\ncontact events"]
    RapierStep --> GameplayStep["Gameplay Rules\nCombatPlay.step()\nRaceCheckpointLapPlay.step()\nWaveSpawnDirector.step()\ndrain event queues"]
    GameplayStep --> WeaponStep["Weapon Systems\nProjectileWeaponSystem.step()\nProjectileManager update\ncooldown timers"]
    WeaponStep --> BehaviorStep["NPC Behavior\nAgentPathNavigator.step()\nNearbyAvoidanceSteering.step()\nCombatBehaviorDirector.step()"]
    BehaviorStep --> CameraStep["Camera Rig\nupdate(actorPose)\nsmoothVector lag\napplyToCamera()"]
    CameraStep --> HUDStep["HUD\nDomHudRenderer.update()\nMinimapProjector2D.update()\nNotificationQueue.step()"]
    HUDStep --> VFXStep["Visual Effects\nJetFlame.update()\nTireMarkRenderer.update()\nWeaponEffectsSystem.update()"]
    VFXStep --> RenderStep["THREE.WebGLRenderer\nrender(scene, camera)"]
    RenderStep --> RAF