SceneGraph shape components: RoundedRectangle, Circle, Triangle, Polygon (#61)

[markwpearce]

Summary

Ships four SceneGraph components — RoundedRectangle, Circle, Triangle, Polygon — that behave like native nodes (e.g. <Rectangle>) but render shapes SceneGraph has no built-in node for, using BGE.Renderer internally. ropm install the engine, drop one tag in a scene, get a rendered shape with no offscreen-bitmap plumbing of your own.

Closes #61.

What's shipped

• src/components/Shapes/{RoundedRectangle,Circle,Triangle,Polygon}.{xml,bs} — each a Group wrapping a child Poster and one persistent, shared ShapeRenderTask instance (src/components/Shapes/ShapeRenderTask.{xml,bs}).
• Fill + outline + shape-specific fields (cornerRadius, outlineSegments, vertices). Triangle/Polygon's vertices is a vector2darray, settable directly as an XML attribute.
• Renders are cached by content-hash filename in cachefs:/ — identical field values reuse the same render permanently across app relaunches, not just within a session.
• examples/scenegraph — the engine's first pure-SceneGraph example (no roScreen/BGE.Game anywhere), demonstrating all four shapes plus a stress-test scene (--param scene=stress) exercising 20-30 concurrent instances.
• docs/scenegraph-shapes.md — usage guide, "How it works," and every hardware finding below.
• specs/2026-08-24-scenegraph-shape-components-design.md — full design history.

Hardware findings (all confirmed on a real device, not the simulator)

• Finish() alone (no roScreen anywhere in the process) is sufficient to realize a Triangle/Polygon's one-time getRightTriangleResource() build — the load-bearing risk this issue called out up front.
• roFileSystem fails on the render thread; MatchFiles() doesn't have that restriction.
• A Poster-extends design (the natural first approach) let Poster's native auto-scale-to-fit stretch a stale bitmap into a newly-set size while a redraw was still in flight, visibly distorting shapes (e.g. elliptical rounded-rect corners) during any width/height change. Fixed by wrapping in Group with an internal Poster whose width/height are never set.
• Every shape costs ~150-200ms per redraw (PNG encode/decode dominates, not draw complexity) — none are animate-safe at a real per-frame rate. Moving the redraw to a shared Task removes render-thread blocking in the common case, but not entirely: with several shapes redrawing concurrently, residual heartbeat gaps up to ~287ms (4 shapes) / ~848ms (30 shapes) remain, traced to the internal Poster's required synchronous image decode (loadSync="true" — needed to avoid a worse bug: async loads went blank under rapid uri churn).
• SceneGraph fires a field's change notification once per attribute, not once per XML tag — several attributes set on one tag used to trigger several real redraws. Fixed with a duration="0" debounce Timer; confirmed on-device with direct call-count instrumentation that N attribute changes now coalesce into exactly 1 real redraw (including the zero-attribute default-render case).
• Default useBitmapPooling: true preallocated ~44MB per shape instance, exhausting memory past ~20-25 concurrent shapes. Fixed with useBitmapPooling: false (each shape's Renderer is one-shot/disposable, so pooling had no benefit to lose).

Known, undstill-open limitation

Mixing all four shape types at 30 concurrent instances non-deterministically drops 4-6 shapes with no visible error. Root cause not identified; documented in docs/scenegraph-shapes.md's "Mass construction" section rather than left unmentioned. rects:30 (single shape type) and mixed:20 are both clean.

Testing

• npm run lint / npm run validate / npm run test:ci (744 passed) / npm run test:ropm-consumer all pass, matching this repo's documented baseline (one pre-existing unrelated lint warning, 3 known upstream emitDefinitions typedef errors).
• Every claim above was independently reproduced on a real Roku device with fresh instrumentation across multiple verification passes, not taken on a single agent's report.

🤖 Generated with Claude Code

[markwpearce]

All the "code behind" files should declare the type of m

for example:

typecast m as ICircle

interface ICircle
  top as INodeCircle
  image as roSGNodePoster
  redrawTimer as roSGNodeTimer
  ' etc.
end interface


interface INodeCircle extends roSGNode
    color as integer
    width as float
    height as float
    ' etc.
end interface

[markwpearce]

Use an interface for exact typing here

[markwpearce]

Replaced with typed ShapeCacheCheck/ShapeRenderState interfaces for checkShapeCache()/createShapeRenderState()/finishShapeRender(), and roTimespan typing for the round-trip timer helpers, in 4a3b00f.

[markwpearce]

Applied across all five component codebehinds (`RoundedRectangle`/`Circle`/`Triangle`/`Polygon`/`ShapeRenderTask`) in 4a3b00f: each now starts with `typecast m as I`, backed by an `INode extends roSGNode` interface (typed against that shape's actual XML fields) and an `I` interface typing `top` plus every child node found via `findNode()` (`roSGNodePoster`, `roSGNodeTimer`, a shared `INodeShapeRenderTask` for the render Task). `ShapeComponentHelpers.bs`'s loosely-typed `as object` returns are now `ShapeCacheCheck`/`ShapeRenderState` interfaces too. Compiles clean under `npm run validate`.