Type-Safe Coordinate Spaces: Preventing Local/World/Screen Coordinate Mixing

[nojaf]

Problem

Kaplay uses three distinct coordinate spaces:

• Local coordinates (pos) - relative to parent object
• World coordinates (worldPos) - relative to root/scene
• Screen coordinates (screenPos, mousePos) - relative to camera/viewport

Currently, all of these are typed as Vec2, which means it's easy to accidentally mix coordinate spaces. For example:

// This compiles but is wrong - mixing local and world coordinates
const target = obj.pos(); // local
agent.setTarget(target); // expects world coordinates

// Or this - mixing screen and world
const mouse = k.mousePos(); // screen coordinates
const worldRect = new Rect(mouse, 100, 100); // might expect world?

These bugs are subtle and can be hard to catch, especially when objects are at the root level where local and world coordinates happen to coincide.

Proposed Solution: Branded Types

TypeScript's type system can provide compile-time safety using branded types or separate classes. Here's how it could work:

// Option 1: Branded types
type LocalVec2 = Vec2 & { readonly __brand: 'local' };
type WorldVec2 = Vec2 & { readonly __brand: 'world' };
type ScreenVec2 = Vec2 & { readonly __brand: 'screen' };

// Option 2: Separate classes (zero runtime cost)
class LocalVec2 extends Vec2 {
  private readonly __brand = 'local' as const;
}
class WorldVec2 extends Vec2 {
  private readonly __brand = 'world' as const;
}
class ScreenVec2 extends Vec2 {
  private readonly __brand = 'screen' as const;
}

This provides compile-time safety - the type system prevents mixing coordinate spaces:

// ✅ Correct
const worldPos: WorldVec2 = obj.worldPos();
agent.setTarget(worldPos);

// ❌ Type error - can't mix local and world
const localPos: LocalVec2 = obj.pos();
agent.setTarget(localPos); // Compile error!

Implementation Options

Here are three approaches that could work in TypeScript:

Option 1: Branded Types (Recommended)

type LocalVec2 = Vec2 & { readonly __brand: 'local' };
type WorldVec2 = Vec2 & { readonly __brand: 'world' };
type ScreenVec2 = Vec2 & { readonly __brand: 'screen' };

// Helper functions to create typed vectors
function asLocal(v: Vec2): LocalVec2 { return v as LocalVec2; }
function asWorld(v: Vec2): WorldVec2 { return v as WorldVec2; }
function asScreen(v: Vec2): ScreenVec2 { return v as ScreenVec2; }

Pros: Simple, zero runtime cost, works with existing Vec2 class
Cons: Requires type assertions for conversions

Option 2: Separate Classes

class LocalVec2 extends Vec2 {
  private readonly __brand = 'local' as const;
}
class WorldVec2 extends Vec2 {
  private readonly __brand = 'world' as const;
}
class ScreenVec2 extends Vec2 {
  private readonly __brand = 'screen' as const;
}

Pros: More explicit, can add conversion methods
Cons: Slightly more complex, need to ensure instanceof checks work

Option 3: Generic Type Parameter

type Vec2<Space extends 'local' | 'world' | 'screen' = 'local'> = {
  x: number;
  y: number;
  readonly __space: Space;
}

Pros: Single type definition, very flexible
Cons: More complex type signatures, harder to work with in some contexts

API Changes

The API would change from:

pos(): Vec2;
worldPos(): Vec2;
setTarget(target: Vec2): void;
hasPoint(point: Vec2): boolean;

To:

pos(): LocalVec2;
worldPos(): WorldVec2;
setTarget(target: WorldVec2): void;
hasPoint(point: WorldVec2): boolean;

Benefits

1. Compile-time safety - TypeScript catches coordinate space mismatches
2. Better IDE support - Autocomplete shows the expected coordinate space
3. Self-documenting code - Types make coordinate space explicit
4. Zero runtime cost - Type-only changes, no performance impact

Migration Path

This could be introduced gradually:

1. Add new typed methods alongside existing ones (e.g., worldPosTyped(): WorldVec2)
2. Mark old methods as deprecated
3. Eventually remove old methods in a major version

Or introduce it as an opt-in feature via a TypeScript configuration option.

Questions

1. Would this be valuable for the Kaplay TypeScript codebase?
2. Which implementation approach (branded types, classes, generics) would fit best with Kaplay's architecture?
3. Are there any concerns about breaking changes or migration complexity?
4. Would you be open to a PR implementing this, or prefer to handle it internally?

Real-World Impact

This type of coordinate space bug is particularly insidious because:

• It often works correctly when objects are at the root level (where local = world)
• It only breaks when objects are nested or the camera moves
• It's hard to debug because the values look correct, just in the wrong space

Adding type safety would catch these issues at compile time, making Kaplay more robust and easier to use correctly.

---

Related: This would also help clarify the coordinate space expectations for Math.Rect, Math.Circle, etc. - currently it's ambiguous whether they expect local or world coordinates depending on usage context.

[lajbel]

Interesting, might take in account!