prosperon/docs/rendering.md

title, type

title	type
Rendering	docs

Rendering

Prosperon's rendering is data-driven. You create sprites and other drawables, set their properties, and the engine handles drawing them. You never touch the GPU directly.

The Model

Think of it like programming sprites on a classic console:

1. Create a sprite (or text, shape, tilemap, particle emitter)
2. Set its position, image, layer, and visual properties
3. The engine draws everything each frame, sorted and batched automatically

var sprite = use('sprite')

var player = sprite({
  image: "player.png",
  pos: {x: 100, y: 200},
  layer: 5
})

// Move it later
player.pos.x = 150
player.pos.y = 250

That's it. The sprite is registered with the engine when created and drawn every frame until destroyed.

Coordinate System

There are two coordinate spaces:

World space is the game world. The camera's position determines what's visible. If the camera is at [100, 100], that world coordinate is at the center of the screen. X+ goes right, Y+ goes up.

HUD space is the screen itself. [0, 0] is the bottom-left corner, [camera.width, camera.height] is the top-right. HUD elements don't move with the camera.

Layers

Every drawable has a layer — an integer that determines draw order. Lower layers draw first (behind), higher layers draw last (in front).

Within a layer, objects can be sorted by different criteria:

• explicit (default) — engine may reorder for performance
• y-sort — sort by Y position, useful for top-down games where "lower" objects appear in front

Planes

Drawables are organized into planes. A plane is a named group that can have its own resolution, camera, and effects. By default, everything goes into the 'default' plane.

Planes render independently and composite onto the screen. This lets you have a game world at 320x240 pixel-art resolution and a HUD at native resolution, for example.

Effects

Planes and groups of sprites can have effects applied:

• Bloom — threshold + multi-pass Gaussian blur
• Mask — stencil masking using other sprites as the mask shape

Effects are declared in the compositor config and applied automatically. You tag sprites with groups, then apply effects to those groups.

Presentation Modes

The final composited frame is presented to the window in one of three modes:

Mode	Behavior
stretch	Fill the window, may distort
letterbox	Fit inside window, preserve aspect ratio, black bars
integer_scale	Scale by whole numbers only, nearest-neighbor, pixel-perfect

Camera

A camera defines the viewport into the world:

var camera = use('camera')
var cam = camera.make({
  pos: {x: 0, y: 0},
  width: 320,
  height: 240
})

The camera's width and height set the game's internal resolution. The pos determines what world coordinate is at the center of the screen.

Drawable Types

Type	Module	Description
Sprite	sprite	Textured quad with transform, tint, UV mapping
Text	text2d	Rendered text with font, size, wrapping
Shape	shape2d	SDF-rendered rectangles, circles, ellipses, pills
Tilemap	tilemap2d	Grid of tiles on a single layer
Particles	particles2d	Particle emitter producing sprite-like particles
Line	line2d	Polylines and line segments as triangle meshes

All drawable types share common properties: pos, layer, plane, groups, visible, opacity, tint.

How It Works Internally

For those curious about the pipeline (you don't need to know this to use Prosperon):

1. Drawables register with film2d — the internal sprite registry
2. Each frame, the compositor queries film2d for all visible drawables
3. Drawables are sorted by layer, batched by texture/material
4. Effect groups are rendered to intermediate targets, effects applied
5. Planes composite to the screen via the SDL GPU backend
6. The backend uses Metal, Vulkan, or DirectX depending on platform