chore(physics): post-19.5 housekeeping — physicLabel + ignoreGravity deprecation

[obiot]

Three related cleanups against the merged 19.5 PhysicsAdapter API (#1450).

1. physicLabel — adapter identity exposed via world.physic

world.physic used to always be "builtin" (or "none") regardless of which adapter was wired in. Code that wanted to branch on the active physics had to import the concrete class and instanceof it.

New optional PhysicsAdapter.physicLabel field declares the adapter's short identifier:

• BuiltinAdapter.physicLabel = "builtin"
• MatterAdapter.physicLabel = "matter"

Application.resolvePhysicSetting reads it and assigns to world.physic, so user code can now branch on the value without imports:

if (app.world.physic === "matter") {
    // matter-only setup (constraints, native queries, …)
}

Falls back to "builtin" for adapters predating the field — existing third-party adapters keep working.

2. World.step gate fix

The conditional in World.step was acting as an "is physics enabled?" flag:

// before
if (this.physic === "builtin") {
    this.adapter.step(dt);
    this.adapter.syncFromPhysics();
}

This worked previously only because world.physic was always "builtin" for any non-"none" case. Under the new labelling that comparison would have stopped stepping the simulation for matter and any third-party adapter. Now reads this.physic !== "none".

The other === "builtin" checks in World (addBody/removeBody's Body Set, the quadtree refresh in update) are genuinely builtin-specific — they read honestly under the new labelling and stay unchanged.

3. Body.ignoreGravity deprecation

Legacy boolean field that only BuiltinAdapter reads; MatterAdapter silently ignores it. Portable equivalent is gravityScale = 0 (or bodyDef.gravityScale = 0 / body.setGravityScale(0)), which works on every adapter.

• JSDoc marks the field @deprecated since 19.5.0 and points at the portable replacement.
• Both call sites (BuiltinAdapter.applyGravity, Body.update falling-state machine) keep the dual check for backward compat — ignoreGravity = true still works on builtin.
• Body.update's falling/jumping state machine now also gates on gravityScale !== 0 so floating bodies (constructed with gravityScale: 0) no longer get marked falling on a side-on collision. Latent bug surfaced while reviewing the deprecation.

Test plan

• pnpm lint: exit 0
• pnpm test: 3486 passed, 12 skipped (no behavior change)
• pnpm --filter melonjs build: clean
• pnpm --filter @melonjs/matter-adapter build: clean
• Visual: matter platformer + pool example still run identically
• Verify app.world.physic === "matter" evaluates true at runtime under matter

CHANGELOG

Two new bullets under 19.5 Fixed and one under Changed.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Post-19.5 housekeeping that exposes adapter identity through world.physic, fixes the World.step gate so it works under any adapter (not just builtin), and deprecates Body.ignoreGravity in favor of the portable gravityScale = 0.

Changes:

• Add optional PhysicsAdapter.physicLabel, set to "builtin" on BuiltinAdapter and "matter" on MatterAdapter; Application.resolvePhysicSetting propagates it to world.physic with a "builtin" fallback.
• Change World.step gate from physic === "builtin" to physic !== "none" so the simulation steps under any adapter.
• JSDoc-deprecate Body.ignoreGravity (recommending gravityScale = 0) and extend Body.update's falling/jumping gate to also check gravityScale !== 0.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
packages/melonjs/src/physics/adapter.ts	Adds optional physicLabel to the PhysicsAdapter interface with usage docs.
packages/melonjs/src/physics/builtin/builtin-adapter.js	Declares physicLabel = "builtin" on the default adapter.
packages/melonjs/src/physics/world.js	Updates step gate to physic !== "none"; expands JSDoc on world.physic.
packages/melonjs/src/physics/builtin/body.js	Marks ignoreGravity @deprecated; gates falling-state update on gravityScale !== 0 too.
packages/melonjs/src/application/application.ts	Resolves legacyString from adapter.physicLabel with "builtin" fallback.
packages/matter-adapter/src/index.ts	Declares physicLabel = "matter" on MatterAdapter.
packages/melonjs/CHANGELOG.md	Documents the three housekeeping items under 19.5 Fixed/Changed.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.