DebugLines

Debug geometry, as line segments the renderer already knows how to draw.

class DebugLines

import { DebugLines } from '@driftengine/core';

In depth

This is the generator and not a pass, and that is the whole reason it is small: drawLines has shipped on both backends since the polyline batch landed, with a world-space width and a pixel floor so a distant line does not strobe. What was missing was anything that turns what you want to see — a mesh's normals, the colliders a body actually carries — into segments, so every consumer who wanted a normals key wrote the geometry themselves or, far more often, did not.

What its absence has cost, measured rather than supposed. One consumer wrote geometry with downward normals four separate times: their roads, their ditch banks, their roof planes, and every building in their world lit inside out. Each was found by looking at a screenshot and wondering why tarmac was black at midday, because a flipped normal near a lamp is a dimmer surface rather than an absent one and only a directional light makes it plain. A key that draws normals turns each of those into a ten-second job.

Nothing here throws and nothing here allocates after construction. A debug drawer that threw when it ran out of room would take the frame with it at exactly the moment somebody was trying to see what was wrong, which is the opposite of its job; so a segment past capacity is counted in dropped and discarded, and a consumer who cares reads that number and builds a bigger one.

Constructor

`new`

constructor(capacity: number)

Parameter	Type	Description
`capacity`	`number`

Properties

Name	Type	Description
`segments`readonly	`LineSegments`

Accessors

Name	Type	Description
`dropped`get	`number`	Segments asked for since the last `clear` that there was no room for.

Methods

`clear`

clear(): void

`segment`

segment(ax: number, ay: number, az: number, bx: number, by: number, bz: number): void

Parameter	Type	Description
`ax`	`number`
`ay`	`number`
`az`	`number`
`bx`	`number`
`by`	`number`
`bz`	`number`

`normals`

normals(mesh: MeshData, length?: number, stride?: number): void

A spike out of every vertex along its normal.

Parameter	Type	Description
`mesh`	`MeshData`
`length?`	`number`
`stride?`	`number`

stride skips vertices, because a mesh of a hundred thousand vertices is a hundred thousand segments and a screen with nothing legible on it. The default draws them all, which is right for the small piece of geometry somebody is actually staring at.

A mesh built from flat faces has four coincident normals per quad, so what appears is one spike per corner rather than one per face, and that is the honest picture: the attribute is per vertex and this draws the attribute.

`box`

box(cx: number, cy: number, cz: number, hx: number, hy: number, hz: number): void

The twelve edges of a world-axis box.

Parameter	Type	Description
`cx`	`number`
`cy`	`number`
`cz`	`number`
`hx`	`number`
`hy`	`number`
`hz`	`number`

`sphere`

sphere(cx: number, cy: number, cz: number, radius: number, points?: number): void

Three great circles, which is a sphere as far as an eye looking for one is concerned.

Parameter	Type	Description
`cx`	`number`
`cy`	`number`
`cz`	`number`
`radius`	`number`
`points?`	`number`

`circle`

circle(cx: number, cy: number, cz: number, radius: number, ux: number, uy: number, uz: number, vx: number, vy: number, vz: number, points?: number): void

A closed ring of points segments, in the plane the two unit vectors span.

Parameter	Type	Description
`cx`	`number`
`cy`	`number`
`cz`	`number`
`radius`	`number`
`ux`	`number`
`uy`	`number`
`uz`	`number`
`vx`	`number`
`vy`	`number`
`vz`	`number`
`points?`	`number`

The basis is passed in rather than derived from an axis because every caller here already has one, and deriving a perpendicular from an axis has a degenerate case that a caller with a real basis does not need to think about.

`shape`

shape(shape: ConvexShape, px: number, py: number, pz: number, qx?: number, qy?: number, qz?: number, qw?: number): void

One collider, placed by a body's position and orientation.

Parameter	Type	Description
`shape`	`ConvexShape`
`px`	`number`
`py`	`number`
`pz`	`number`
`qx?`	`number`
`qy?`	`number`
`qz?`	`number`
`qw?`	`number`

Dispatched on what the shape is rather than on a stored kind, which is the same discrimination the narrow phase makes: a sideRadius is a cylinder, a triangles is a mesh, a radius over one point is a sphere and over two is a capsule, and anything with faces is a polytope drawn along its own face loops. A shape that grows a new representation appears here as its polytope hull rather than as nothing, which is the failure worth having.

`colliders`

colliders(world: PhysicsWorld): void

Every body's collider in a world, where it is this tick.

Parameter	Type	Description
`world`	`PhysicsWorld`

The other half of the key the report asked for. Bodies with no shape are skipped rather than refused: a world may hold one for a frame while it is being built.