2483e1e894
Phase J (2026-08-03) bumped lib-core.composition 0.3.0->0.4.0 and
lib-core.crafting 0.3.0->0.5.0, but only vagrant-skeleton and
lib-core.crafting themselves were updated. Dependent manifests kept the
old pins, so dep-fetcher saw disagreeing pins on the same lib and
refused to start both spine-prototype (ENGINE_ERR_LIB_DEP_MISSING,
rc=19) and vagrant-skeleton ("dep check failed", conflict on
lib-core.composition + lib-core.crafting).
Unify all pins on the on-disk versions. No code changes required:
composition 0.4.0 is purely additive (the quality/condition loud-error
was removed; no signature changed), and crafting-display only consumes
crafting.can_craft + crafting.list_recipes, both still present, and
never referenced the `form` field retired by ADR-0055.
README "Requires:" lines synced to match the manifests (Gate 3).
milestone-check.sh: GREEN (build, ctest, smoke, devwrap-ci,
test-all-modules + anomaly scan). vagrant-skeleton headless run clean
at 60 CI frames.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
128 lines
4.7 KiB
Markdown
128 lines
4.7 KiB
Markdown
# lib-core.render
|
||
|
||
Colored-quad tile-grid renderer + tag-driven entity-render. Reads
|
||
`lib-core.maps`'s tilemap (v0.1: `draw_map`), and `lib-core.composition`'s
|
||
tag-index (v0.2: `draw_entities`).
|
||
|
||
**Version:** 0.3.0
|
||
**Lib-ID:** lib-core.render
|
||
**Requires:** lib-core.maps v>=0.5.7, lib-core.composition v>=0.4.0
|
||
**Tags:** render, tiles, draw, colored-quads, entities
|
||
|
||
## Topology
|
||
|
||
<!-- topology:start (auto-generated; do not edit) -->
|
||
```mermaid
|
||
graph LR
|
||
this["lib-core.render"]
|
||
lib_core_maps["lib-core.maps"]
|
||
this --> lib_core_maps
|
||
lib_core_composition["lib-core.composition"]
|
||
this --> lib_core_composition
|
||
engine["engine.*"]
|
||
this --> engine
|
||
```
|
||
<!-- topology:end -->
|
||
|
||
## API
|
||
|
||
### `render.draw_map(map_id)`
|
||
**Syntax:** `render.draw_map(map_id: string | nil) -> integer`
|
||
|
||
**Example:**
|
||
```lua
|
||
function render(ctx)
|
||
engine.render.clear_color(engine.render.rgb(20, 20, 30))
|
||
local n = render.draw_map() -- uses current-map
|
||
end
|
||
```
|
||
|
||
**Description:** Iterates the tiles of the specified map (or current-map when nil), drawing one colored rect per tile at `(tx * tile_size, ty * tile_size)`. Tile color is read from the tilemap's `tile.color = {r, g, b}`; if missing or malformed, falls back to magenta as a visible "missing-color" debug-marker. Must be called from inside a render hook. Returns the number of tiles drawn (for smoke verification + debug).
|
||
|
||
### `render.draw_entities(filter)`
|
||
**Syntax:** `render.draw_entities({tag: string}) -> integer`
|
||
|
||
**Example:**
|
||
```lua
|
||
function render_fn(ctx)
|
||
camera.begin()
|
||
render.draw_map()
|
||
render.draw_entities{ tag = "renderable" }
|
||
camera.finish()
|
||
end
|
||
```
|
||
|
||
**Description:** Iterates entities tagged with `filter.tag` (via
|
||
`composition.list_by_tag`) and renders each according to its
|
||
sprite-properties. `position.x`/`position.y` is treated as the visual
|
||
CENTER of the entity in all render-paths. Returns the number of
|
||
entities drawn.
|
||
|
||
Three sprite-property paths are tried per entity, in order:
|
||
|
||
1. **`sprite_atlas` (string, atlas-texture-path) + `sprite_uv.{x,y,w,h}`
|
||
(numbers)** — renders the sub-rectangle of the atlas via
|
||
`engine.render.draw_sprite_transform`. Optional `sprite_scale`
|
||
(number, default 1.0) scales the rendered quad uniformly around its
|
||
visual center; useful when a sprite-atlas's native pixel size
|
||
doesn't match the project tile-scale. Atlas textures are loaded
|
||
once and cached internally on first use; no eviction.
|
||
2. **`sprite_color` (uint32 0xRRGGBBAA) + `sprite_w` + `sprite_h`
|
||
(numbers)** — renders a colored rect via `engine.render.draw_rect`.
|
||
3. **None of the above** — magenta 16×16 fallback rect (debug-marker).
|
||
|
||
Filter shape `{tag = "..."}` is the only supported form in v0.2.0;
|
||
template-id-based or property-predicate filters are deferred (loud-error
|
||
for malformed filters; see Phase-A Spec A-Q3).
|
||
|
||
## Conventions
|
||
|
||
- Colored-quads only in v0.1.0. Texture-rendering, multi-layer composition, post-processing, parallax, shaders, hot-reload all DEPRECATED-MVP.
|
||
- World-space coords; pair with `lib-core.camera` to support panning + zoom.
|
||
- Magenta fallback `[255, 0, 255]` is intentional: high-visibility debug-marker for malformed color-data.
|
||
- Y-down-positive per ADR-0031.
|
||
|
||
## Consumer pattern
|
||
|
||
```lua
|
||
local maps = require("lib-core.maps")
|
||
local render = require("lib-core.render")
|
||
local camera = require("lib-core.camera")
|
||
|
||
function render_fn(ctx)
|
||
engine.render.clear_color(engine.render.rgb(20, 20, 30))
|
||
camera.begin()
|
||
render.draw_map()
|
||
camera.finish()
|
||
end
|
||
```
|
||
|
||
## CHANGELOG
|
||
|
||
### v0.3.0 (2026-06-20)
|
||
- Added optional `sprite_scale` (number) on path (1). Defaults to 1.0
|
||
when absent — v0.2.0 consumers unchanged. Lets templates whose
|
||
native sprite resolution doesn't match the project tile-scale
|
||
rescale at render time without re-baking the atlas.
|
||
- Composition dep tightened to v0.3.0 (matches current sibling-tree
|
||
state; no API impact, just resolution-correctness).
|
||
|
||
### v0.2.0 (Phase A.2 — 2026-06-09)
|
||
- Added `draw_entities(filter)` tag-driven entity-render. Two sprite-
|
||
property paths (`sprite_atlas`+`sprite_uv` / `sprite_color`+`sprite_w`+
|
||
`sprite_h`) plus magenta-fallback. `position.x`/`.y` is visual-center.
|
||
- Atlas-texture cache (no eviction in v0.2.0).
|
||
- New dep: `lib-core.composition` v0.1.0.
|
||
|
||
### v0.1.0 (P.0)
|
||
- Initial release: `draw_map` colored-quad iterator.
|
||
|
||
## References
|
||
|
||
- Spec v0.1.0 (P.0): `meta/docs/superpowers/specs/2026-05-09-p0-lib-render-design.md`
|
||
- Spec v0.2.0 (Phase A): `meta/docs/superpowers/specs/2026-06-09-phase-A-inactive-entities-composition-actor-reentry-design.md`
|
||
- Architecture: `meta/docs/architecture/render-pipeline.md`
|
||
- ADR-0001 (engine knows verbs, libs bring nouns)
|
||
- ADR-0031 (pixel-convention: Y-down-positive)
|
||
- ADR-0038 (API-Doc-Convention)
|