Cameras

Use a 2D camera for canvas layers or a 3D camera for a mounted world.

Camera 2D

Camera2DSettings pans and zooms an inclusive range of drawing layers. Layers outside that range stay fixed for HUDs and menus.

func showWorld(game *engine.Game) engine.Camera2DSettings {
    camera := engine.Camera2DSettings{
        Position: engine.NewVec2(400, 300),
        Zoom: 2,
        WorldMinLayer: 0, WorldMaxLayer: 100,
    }
    game.SetCamera2D(camera)
    return camera
}

At 960 by 540, world point (400, 300) appears at screen centre (480, 270). Zoom two doubles displayed distances. A HUD on layer 1000 stays fixed.

Scroll to see all columns.

Conversions must use the settings sent to the host and the project's authored width and height. Browser CSS dimensions do not belong here.

Zoom must be finite and within 1/64 to 64. The minimum layer cannot exceed the maximum. There is one active ordinary 2D camera.

Camera 3D · Willowbrook camera · Pointer picking

Exact bounds are in .karty/docs/cameras.md.

Camera 3D

Camera3D projects a mounted world into a 2D output rectangle. Create it inside a level's ready callback, using that event's handle.

func roomCamera(game *engine.Game, level engine.LevelHandle) *engine.Camera3D {
    return game.NewCamera3D(level, engine.Camera3DSettings{
        Projection: engine.CameraProjectionPerspective,
        Output: engine.CameraOutputFull,
        Position: engine.NewVec3(2, 2, 1.7),
        VerticalFOV: 1.05, OrthoHeight: 12,
        NearClip: 0.05, FarClip: 100,
        ViewportWidth: 960, ViewportHeight: 540,
    })
}

Scroll to see all columns.

Use camera.Ref().SetPose(pose) to propose a free camera's world pose and camera.SetSettings(settings) to change projection and other camera settings. An attached body controls position; use its movement methods or Body.Teleport for positional changes. The entity's 2D transform places the rendered output on the canvas. Use a lower drawing layer to put it behind HUD elements.

Use accepted poses for movement, as described in Transform 3D. Destroy removes the camera; level release also removes it. Camera count and viewport bounds are in .karty/docs/cameras.md.

Hangar camera setup · Isometric guide

First-person player

The controllers-3d package supplies the first-person controller. Its controllers-3d.sdk build processor generates a typed adapter for your project. After creating a camera in a ready level, attach the controller:

// Import the package-generated adapter as fpscontroller from
// "YOURMODULE/.karty/processed/code/controllers-3d.sdk/controller".
func attachPlayer(game *engine.Game, camera *engine.Camera3D) (*fpscontroller.FirstPersonController, error) {
    options := fpscontroller.DefaultFirstPersonOptions()
    options.Speed = 4 // metres per second
    return fpscontroller.AttachFirstPerson(*game, camera, options)
}

It owns keyboard and pointer input, mouse capture, visible touch sticks and a physics body with gravity and collision. It moves before the game's OnUpdate; keep ordinary hooks for interactions and other game actions.

The game owns the camera. The controller cleans up its body and display when closed, when the camera is destroyed, when its level is released, or at cartridge shutdown. Only one local controller can be attached at a time. SetEnabled(false) releases held controls; Teleport clears input and momentum while retaining the camera and body. FirstPersonFree mode omits the body for an inspection camera. BeforeMove and Move extend movement for authored rules.

First-person guide · Hangar traversal

Exact options and lifecycle rules are in the installed package's README and component documentation under .karty/packages/controllers-3d/.