ExoJS keeps two coordinate systems in mind at once. Drawables are positioned in world space — the coordinate system you write game logic in. Input and view APIs use logical canvas space, also called design or screen space. A View sits between the two and handles the mapping.
Understanding this split makes camera follow, zoom, split-screen, and HUD overlays straightforward. Confusing them is the source of most “the position is wrong” bugs.
World space
When you call sprite.setPosition(400, 300), you’re setting a position in world space. The numbers you choose are the same numbers your game logic operates on — distances, velocities, hit boxes. They have nothing to do with the user’s screen.
In a typical 2D project, world space has the X axis pointing right and the Y axis pointing down (matching browser conventions). The origin is wherever you put it; many projects use (0, 0) as the world’s center, others put it at the top-left of the playable area.
Canvas space
Canvas space runs from (0, 0) at the top-left to (app.width, app.height) at the bottom-right. Pointer events arrive in these logical design pixels, independent of CSS size and device pixel ratio. The surface’s app.canvas.width and app.canvas.height are physical backing-store dimensions and are normally only relevant to low-level rendering code.
If you placed every sprite at its world position and the camera never moved, world space and canvas space would line up exactly. The moment you move the camera, scale the canvas, or render to a sub-region, the two diverge.
The active view
Every render backend exposes a view property. The view defines how world space maps onto the canvas:
view.center — the world-space point at the center of the canvas.
view.size — how much world space fits inside the canvas.
view.rotation — the camera’s rotation in degrees.
view.viewport — which sub-region of the canvas the view paints into (default: the whole canvas).
Set the center to (400, 300) and the size to (800, 600), and the canvas shows the world from (0, 0) to (800, 600). Move the center to (400, 600) and the camera scrolls down by 300 pixels’ worth of world.
You don’t usually configure the view by hand — it tracks the canvas size automatically. Reach for setCenter, move, setZoom, and setRotation when you need to script view behavior. Access the active view through the context passed to draw, using context.view.
Following an object
The view supports following a target. The target can be any object with x and y properties — typically a scene node, but a plain {x, y} object works too:
Following keeps the view centered on the target while the scene renders. Call context.view.clearFollow() to detach. If you want smoothing, keep a small camera target object and move it toward the player in update, then follow that target instead of the player directly.
Zooming
The setZoom(z) method scales how much world fits inside the view. setZoom(2) means the view shows half as much world as it normally would (everything looks twice as big). setZoom(0.5) does the opposite (everything looks zoomed out). The zoomIn(amount) and zoomOut(amount) helpers adjust relative to the current zoom.
examples/guides/coordinates-and-views/views.ts
override init(): void { this.zoom = 1; this.inputs.onTrigger(Keyboard.Equal, () => { // the key printed =/+ on US QWERTY this.zoom += 0.1; });}override draw(context: RenderingContext): void { context.view.setZoom(this.zoom); context.render(this.world);}
Common pitfalls
A handful of misalignments come up regularly:
Hardcoded canvas-relative positions. Setting a sprite to (400, 300) because that “looks centered for an 800×600 canvas” breaks the moment the canvas resizes. Use the active view’s center, the canvas size at runtime, or anchor-aware containers instead.
Anchor confusion. A sprite’s position is the world-space location of its anchor. The default anchor is the top-left, so setPosition(400, 300) puts the top-left of the sprite at (400, 300), not its middle. Call setAnchor(0.5) to pivot at the center.
Pointer events without view conversion. Pointer events arrive in logical canvas space. If your camera has moved, you need to convert them back to world space before testing whether the click hit a world-space object. The world-vs-screen-coords example below shows the conversion.
HUD inside the world. A health bar should not move when the camera moves. Add HUD elements to scene.ui; it stays in logical canvas space and renders above the world automatically.
Multiple views
The active view can be swapped on every frame. Used together with viewports, this gives you split-screen, picture-in-picture, and minimap rendering — render the world once with one view configuration into one viewport, then again with a different configuration into another:
The same scene graph rendered with two different view configurations, into two halves of the canvas — one tree, two views. The viewport fractions are normalized (0–1 of canvas size), so setViewport(0, 0, 0.5, 1) covers the left half and setViewport(0.5, 0, 0.5, 1) covers the right. If you continue rendering HUD elements or additional scenes afterward, reset the viewport before those passes so later rendering does not inherit the split-screen configuration.