Skip to main content

Instance tree & reflection

Where: App/v8tree/, App/reflection/, headers under App/include/V8Tree/ and App/include/reflection/

Everything in a Roblox game is a node in one tree. The node type is RBX::Instance.

RBX::Instance​

App/v8tree/Instance.cpp (header: V8Tree/Instance.h) implements the base class every game object derives from — Part, Decal, Script, Workspace, Humanoid, …

Core responsibilities:

  • Tree membership — parent/child links, getChildren, name-based lookup (FindFirstChild, IsA, …) — the methods you know from the Lua API are bound directly on this class.
  • Lifecycle — Clone, Destroy/Remove, archivability, locking.
  • Reflection registration — exposes its scripting surface (see below).
  • Serialization hooks — knows how the XML/binary serializers visit it (V8Xml/Serializer.h).
  • Change notification — property and ancestry changes propagate to listeners (adornments, replication, the Studio property grid).

Related primitives in App/v8tree/:

FilePurpose
Instance.cppThe base class (reflection registration of Instance itself)
Property.cppGeneric property values flowing through reflection
Verb.cpp"Verbs" — editor commands/actions (insert, delete, group…)
Service.cppBase class for DataModel services
EnumProperty.cppEnumerated property support

The reflection system​

Reflection lives in App/reflection/ (reflection_object.cpp, reflection_property.cpp, reflection_function.cpp, Event.cpp, Callback.cpp, type.cpp). It is the single source of truth for an object's scripting & editing surface.

A typical registration, from Instance.cpp:

REFLECTION_BEGIN();

Reflection::PropDescriptor<Instance, bool> Instance::propArchivable(
"Archivable", category_Behavior,
&Instance::getIsArchivable, &Instance::setIsArchivable,
Reflection::PropertyDescriptor::SCRIPTING);

static Reflection::BoundFuncDesc<Instance, bool(std::string)> func_isA(
&Instance::isA, "IsA", "className", Security::None);

static Reflection::BoundFuncDesc<Instance, shared_ptr<Instance>(std::string, bool)>
findFirstChild(&Instance::findFirstChildByName2, "FindFirstChild",
"name", "recursive", false, Security::None);

What this buys the engine:

  • The Lua API — LuaInstanceBridge (see Scripting) binds reflected properties/methods/events into the Lua VM automatically. Deprecations are expressed as duplicate descriptors (note the lowercase archivable/clone/remove legacy bindings).
  • Security levels — every descriptor carries a Security:: context (e.g. Security::None vs. plugin/core-script-only surfaces). See Security.
  • The Studio UI — property grids, category ordering (category_Behavior, …) come straight from the descriptors.
  • Serialization — the XML and binary serializers enumerate reflected properties (see Serialization).

Descriptor flavors​

DescriptorDescribes
PropDescriptor<T, V>A typed property with getter/setter, category and security
BoundFuncDesc<T, R(Args...)>A bound member function (Lua method)
Event / CallbackScriptable events and callbacks
Enums (EnumProperty.cpp, LuaEnum bridge)Enum types exposed to scripts

Fast tree access​

Naïve parent/child traversal is not enough for a scene with millions of parts, so the engine keeps auxiliary indexes — see App/util/IndexedTree.* (indexed name/class lookups) and the spatial structures described in Physics.