defold / defold/extension-rive

Feature request: expose node identity in the scripting API (NodeData.name / component source)

Open
#260 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
C++
Stars
73
Forks
15
Avg merge
1d 21h
Merged PRs (30d)
3

Description

Summary

NodeReadData/NodeData in Luau scripting currently expose transforms (position, rotation, scale, worldTransform), hierarchy (parent, children), decompose, and asPath. There is no way to identify what a traversed node is: no name, no type discriminator, and no way to reach the source artboard of a placed component instance. Name resolution only works in one direction — Artboard:node(name) — so a script can find a node it already knows the name of, but a node discovered through children traversal is anonymous and opaque.

Requested additions (any subset helps)

NodeData.name: string? — the node's name, subject to the same export-name rules that Artboard:node() lookup already respects.
NodeData:asArtboard() -> Artboard? (or a sourceArtboardName: string? field) — for nodes that are nested artboard / component instances, access to the instance or at least the name of its source artboard. This is the source value the editor already tracks on nested artboards; it just isn't surfaced to scripting.
Optionally a lightweight type discriminator (e.g. nodeType: string — "node" | "shape" | "path" | "nestedArtboard" | ...), in the spirit of the existing asPath() pattern.

Use case

We're building a game where a full-screen Rive artboard is the world (Defold runs the simulation and drives the view via data binding). A Node script traverses the world artboard's hierarchy at load to extract authored content — floor tiles, walls, machine placements, collision footprints — and publishes it to the host engine through a ViewModel.

Because traversed children are anonymous, the script cannot tell a placed WallNS component from a WallEW component, or either from a decorative group. We currently work around this with authoring conventions:

Semantic export-named root groups per type (WallNSPlacement Group, WallEWPlacement Group, ...) — type is encoded by which root a node sits under, which constrains how artists are allowed to organize the file.
Where that breaks down, indexed export-name probing (map:node("WallNS_" .. i) until nil) — which requires manually naming and export-flagging every placed instance.

With NodeData.name or component-source access, a script could simply walk the tree and read what each placement is — no naming conventions, no per-instance flags, and files stay freely organizable for artists.

This generalizes beyond games: any script that treats the authored hierarchy as data (level layouts, diagram semantics, generated content manifests) hits the same wall.

Environment

Verified against the current editor's built-in Luau typedefs and the current online docs for NodeReadData/NodeData — both agree on the surface described above. The paint/asPaint "coming soon" markers suggest this surface is still growing, which is why we're hopeful identity access is on (or can join) the roadmap.

Thanks for considering it — the scripting system is already carrying an entire game world for us, and this is the one place we've had to route around it rather than through it.

Contributor guide

No contributing guide indexed for this repository

Research direction

Start by reviewing the current Luau typedefs and online NodeReadData/NodeData documentation mentioned in the issue, then trace how Artboard:node(name), children traversal, asPath(), and nested artboard source values are exposed. Done means agreeing on and documenting an identity API that lets traversed nodes be identified, including component-source access if supported, with corresponding coverage in the scripting surface.

Written by the indexing model from the issue text.

Assessment

Domain
api
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.