Skip to content

refactor(api): Phase 2 — seal public API, migrate demo concepts out of core - #11

Draft
dioveath wants to merge 8 commits into
mainfrom
cursor/phase-2-api-seal-1b72
Draft

dioveath wants to merge 8 commits into
mainfrom
cursor/phase-2-api-seal-1b72

Conversation

@dioveath

@dioveath dioveath commented Jul 3, 2026

Copy link
Copy Markdown
Owner

Summary

Phase 2 of the engine cleanup: seal the public API so teengine exports only engine primitives. Demo-specific concepts move to examples/demo.

Changes

Entity model

  • Removed PlayerTag, CoinTag, CameraTargetTag, CollisionListenerTag from core
  • Added tags: Set<string> on Entity / SpawnConfig
  • CameraFollowSystem now takes (camera, followTag) — tag is game-defined

Public API trimmed (index.ts is the only contract)

Removed from exports:

  • DemoAtlas, GpuTexture, CollisionGroups presets
  • ColliderHandle, coordinate helpers (engineToRapier, etc.)

Added to exports:

  • hasPhysics, isSimulatedBody, TransformData, shape component types
  • uploadRgbaTexture(engine, pixels, w, h)

Asset loading

  • Removed public Engine.device getter
  • loadAtlasFromJson(engine, url) — engine passed instead of raw GPUDevice
  • uploadRgbaTexture for procedural/custom textures (demo uses this)

Demo migration

New examples/demo/src/demoConstants.ts:

  • DemoTags — player, coin, cameraTarget
  • DemoAtlas — demo atlas shape
  • DemoCollisionGroups — PLAYER, PICKUP, GROUND, ENEMY bits

All demo systems updated to use tags and demo-owned collision constants.

Docs

  • MODULES.md, ARCHITECTURE.md, PACKAGE.md updated — Phase 2 items marked done

Verification

  • npm run typecheck (engine + demo) — clean
  • npm run test -w teengine — 37/37 passing
  • npm run build -w teengine — clean

Breaking changes (intentional)

Consumers upgrading must:

  1. Replace tag components with tags: ["player"] etc.
  2. Pass Engine to loadAtlasFromJson instead of GPUDevice
  3. Define their own collision layer bit constants (see demo)
  4. Pass followTag to CameraFollowSystem
Open in Web Open in Cursor 

cursoragent and others added 8 commits July 3, 2026 16:17
Define Kernel/Core/Standard/Application tiers with classification rules,
fixed-update pipeline phases, export map, and full character-controller
module spec. Update architecture, package, and physics docs to reference
the new source of truth.

Co-authored-by: rAI <raisaroj360@gmail.com>
Replace tiered module spec with a single boundary rule: the package
provides run/draw/simulate/input. Character controllers, animation,
and scene management are developer or example concerns, not engine work.

Co-authored-by: rAI <raisaroj360@gmail.com>
createPhysicsForEntity() bakes collider.offset into the body's initial
translation, but syncToEntities() wrote the body position straight back
to entity.transform without subtracting it — any entity with a non-zero
offset would jump by that offset on the first physics sync.

PhysicsWorld now stores the offset per entity and getTransformForEntity()
subtracts it back out. PhysicsBridge.syncToEntities() uses that
entity-aware lookup instead of the raw handle-based getTransform().

Co-authored-by: rAI <raisaroj360@gmail.com>
DEFAULT and PLAYER were both 1 << 0 — composing DEFAULT into a mask
silently also matched PLAYER and vice versa. Re-numbered so each
preset owns a unique bit, and added a test that locks this invariant
in going forward.

Co-authored-by: rAI <raisaroj360@gmail.com>
…ner no-op

Traced the branches: Rapier only queues events for a collider whose
resolved emitEvents is true in the first place, so by the time
shouldEmitAsSelf's first guard passes, every remaining branch already
evaluates to true (sensor, or a solid with emitEvents explicitly set —
the only way a solid's resolved emitEvents becomes true). The function
reduces to returning collision.emitEvents; collisionListener currently
has no effect on the outcome, which is documented as a tracked Core API
cleanup rather than silently changed here.

Added collisionDefaults.test.ts covering resolveCollision defaults and
shouldEmitAsSelf, since neither had direct unit tests before.

Co-authored-by: rAI <raisaroj360@gmail.com>
…e API

The example called world.attachPhysics() and world.syncFromPhysics(),
neither of which exist — physics is constructor-injected into World,
and sync happens internally inside World.fixedUpdate(). It also nested
collider inside rigidBody, which contradicts the actual sibling-component
schema. Replaced with a runnable example matching PlayerControllerSystem
and DemoScene in examples/demo.

Co-authored-by: rAI <raisaroj360@gmail.com>
- Replace PlayerTag/CoinTag/CameraTargetTag/CollisionListenerTag with
  Entity.tags: Set<string>
- CameraFollowSystem takes followTag string (game-defined)
- Remove DemoAtlas, CollisionGroups presets, ColliderHandle, coord
  helpers, and GpuTexture from public exports
- Reconcile index.ts as the single API contract; export hasPhysics,
  isSimulatedBody, TransformData, shape component types

Co-authored-by: rAI <raisaroj360@gmail.com>
…ate demo

- Remove public Engine.device; asset helpers use getGpuDevice() internally
- Add uploadRgbaTexture(engine, pixels, w, h) for procedural textures
- Demo owns DemoTags, DemoAtlas, DemoCollisionGroups in demoConstants.ts
- Update docs (MODULES, ARCHITECTURE, PACKAGE) for Phase 2 completion

Co-authored-by: rAI <raisaroj360@gmail.com>
@coderabbitai

coderabbitai Bot commented Jul 3, 2026

Copy link
Copy Markdown

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 6d9c1eac-4a63-4c32-903f-bd8cb6001ebc

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

  • 🔍 Trigger review
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch cursor/phase-2-api-seal-1b72

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants