Skip to content

Add a 2.5D platformer example validating the Camera3d + Octree + SAT pattern #1476

@obiot

Description

@obiot

Why

The 19.7 Camera3d + Octree work documents a 2.5D recipe in the wiki: Working in 3D — 2.5D Games (Paper Mario-style). Short version:

  • cameraClass: Camera3d for the perspective look
  • All gameplay entities on a shared Z (e.g. z = 0)
  • Parallax layers at distinct Z values
  • Existing 2D SAT collision (me.collision.check, Body shapes, world.adapter.queryAABB) works as-is because SAT runs on Rect/Polygon/Ellipse in the XY plane and doesn't care which camera class renders them
  • Octree broadphase as a side effect gives free Z isolation between gameplay and parallax — background sprites can't accidentally enter the bullet/enemy candidate list

The recipe is sound on paper, but no example currently exercises it end-to-end. AfterBurner is a true-3D arcade shooter (varied Z, sphere queries in 3D space) and the platformer example uses Camera2d. We need a worked reference for the in-between case.

Scope

A small, self-contained 2.5D platformer at packages/examples/src/examples/platformer25d/ (or similar). MVP, not a polished game:

  • Camera3d in chase / sidescroll-with-slight-perspective configuration
  • Player (Sprite or simple Mesh) on the gameplay Z plane
  • 2-3 enemies on the gameplay Z plane with SAT-driven Body collision
  • A few tile platforms with SAT collision (Tiled map or hand-built, either is fine)
  • 2-3 parallax layers at distinct Z (foreground props in front, mid trees, distant mountains)
  • Optional: a coin / pickup loop to give the level something to do
  • No procedural audio polish, no shaders, no juicy particles — keep it focused on validating the architectural pattern

What this validates

  • cameraClass: Camera3d + 2D SAT collision compose cleanly with no per-call-site Rect → AABB3d lifting
  • world.adapter.queryAABB(playerBox) returns the gameplay-Z candidates (player vs enemies vs platforms) and skips parallax layers automatically because their Z slabs don't overlap
  • Octree overhead stays acceptable at typical 2.5D entity counts (target: a few dozen bodies, easily within budget)
  • Painter sort under world.sortOn = "depth" correctly layers parallax fore/back relative to gameplay without manual ordering

What this might surface

Some friction we should be ready to find:

  • addChild(child, z) ergonomics under perspective — does the Z math read naturally for a 2D dev's mental model?
  • Whether ortho-style screen-space input/picking (mouse, touch) on a perspective camera needs documentation we haven't written yet (related to the deferred localToWorld / worldToLocal 3D unproject in feat(camera): Camera3d + Frustum + Stage/App cameraClass (19.7.0 PR B) #1464's known-limitations)
  • Whether the existing Camera2d follow / lookAhead semantics survive being subclassed under Camera3d for sidescroll use
  • Any surprises in the Builtin adapter's queryAABB when the broadphase is Octree and the query Rect needs lifting

If any of these surface, the fix is part of this issue (engine side) or just doc/wiki improvements (example side).

Out of scope

  • Full 3D platforming (jumping in/out of Z) — that's a true-3D problem, not 2.5D
  • Box2D / planck-style physics — Builtin adapter only
  • Polished art / sound / particles — those belong in a follow-up showcase repo if the validation succeeds

Reference

Working in 3D — 2.5D Games (Paper Mario-style) is the canonical spec. The example should be the worked reference the wiki links to, mirroring the AfterBurner pattern (wiki documents the surface, example demonstrates it in tree).

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions