gaia::ecs::ComponentCursor Struct Reference

Stack-only cursor over raw component bytes and runtime field metadata. More...

#include <component_cursor.h>

Public Member Functions
	ComponentCursor ()=default
	Creates an invalid cursor.
GAIA_NODISCARD bool	valid () const noexcept
GAIA_NODISCARD uint32_t	depth () const noexcept
GAIA_NODISCARD Entity	type () const noexcept
GAIA_NODISCARD uint32_t	size () const noexcept
GAIA_NODISCARD const void *	ptr () const noexcept
GAIA_NODISCARD void *	mut_ptr () const noexcept
GAIA_NODISCARD uint32_t	field_count () const
bool	field (uint32_t index)
	Descends into the reflected field at index.
bool	field (util::str_view name)
	Descends into the reflected field named name.
bool	parent () noexcept
	Moves back to the parent cursor scope.
GAIA_NODISCARD bool	get_f32 (float *value) const noexcept
	Reads the current cursor bytes as a scalar f32 convenience value.
ComponentWriteResult	write_bytes (const void *data, uint32_t byteCount) noexcept
	Writes exact bytes to the current cursor position.

Static Public Member Functions
static GAIA_NODISCARD ComponentCursor	from_raw (const ComponentCache &components, Entity component, ComponentRawView view)
	Creates a read-only cursor from a raw component view.
static GAIA_NODISCARD ComponentCursor	from_raw (World &world, const ComponentCache &components, Entity entity, Entity component, ComponentRawMutView view)
	Creates a mutable cursor from a raw component view.

Static Public Attributes
static constexpr uint32_t	MaxDepth = 32
	Maximum nested field depth tracked by the cursor.

Detailed Description

Stack-only cursor over raw component bytes and runtime field metadata.

The cursor is a short-lived non-owning view. It never owns component bytes or metadata and is invalidated by structural changes that can move component storage. Field navigation is strict: missing fields, unsupported type metadata, and out-of-bounds field ranges leave the cursor unchanged.

Member Function Documentation

depth()

GAIA_NODISCARD uint32_t gaia::ecs::ComponentCursor::depth ( ) const

inlinenoexcept

Returns

Current nesting depth. Root payload is depth 0.

field() [1/2]

bool gaia::ecs::ComponentCursor::field ( uint32_t  index )

inline

Descends into the reflected field at index.

Parameters

index

Reflected field index on the current type.

Returns

True when the cursor moved to the field.

field() [2/2]

bool gaia::ecs::ComponentCursor::field ( util::str_view  name )

inline

Descends into the reflected field named name.

Parameters

name	Reflected field name on the current type.

Returns

True when the cursor moved to the field.

field_count()

GAIA_NODISCARD uint32_t gaia::ecs::ComponentCursor::field_count ( ) const

inline

Returns

Number of reflected fields on the current type.

from_raw() [1/2]

static GAIA_NODISCARD ComponentCursor gaia::ecs::ComponentCursor::from_raw ( const ComponentCache &  components, Entity  component, ComponentRawView  view  )

inlinestatic

Creates a read-only cursor from a raw component view.

Parameters

components	Component metadata registry used for field/type lookup.
component	Component/type entity represented by view.
view	Raw component view returned by World::get_raw().

Returns

Cursor positioned at the root component payload, or invalid cursor when view is invalid.

from_raw() [2/2]

static GAIA_NODISCARD ComponentCursor gaia::ecs::ComponentCursor::from_raw ( World &  world, const ComponentCache &  components, Entity  entity, Entity  component, ComponentRawMutView  view  )

inlinestatic

Creates a mutable cursor from a raw component view.

Parameters

world	World owning the mutated chunk storage.
components	Component metadata registry used for field/type lookup.
entity	Entity whose component payload is represented by view.
component	Component/type entity represented by view.
view	Raw component view returned by World::mut_raw().

Returns

Cursor positioned at the root component payload, or invalid cursor when view is invalid.

get_f32()

GAIA_NODISCARD bool gaia::ecs::ComponentCursor::get_f32 ( float *  value ) const

inlinenoexcept

Reads the current cursor bytes as a scalar f32 convenience value.

Parameters

value

Receives the read value.

Returns

True when the current cursor position is exactly one f32 value.

mut_ptr()

GAIA_NODISCARD void * gaia::ecs::ComponentCursor::mut_ptr ( ) const

inlinenoexcept

Returns

Mutable pointer at the current cursor position. Null for read-only cursors, tags, and invalid cursors.

parent()

bool gaia::ecs::ComponentCursor::parent ( )

inlinenoexcept

Moves back to the parent cursor scope.

Returns

True when the cursor moved to the parent; false at root or when invalid.

ptr()

GAIA_NODISCARD const void * gaia::ecs::ComponentCursor::ptr ( ) const

inlinenoexcept

Returns

Read-only pointer at the current cursor position. Null for tags and invalid cursors.

size()

GAIA_NODISCARD uint32_t gaia::ecs::ComponentCursor::size ( ) const

inlinenoexcept

Returns

Current payload or field size in bytes.

type()

GAIA_NODISCARD Entity gaia::ecs::ComponentCursor::type ( ) const

inlinenoexcept

Returns

Current component/type entity, or EntityBad for an invalid cursor.

valid()

GAIA_NODISCARD bool gaia::ecs::ComponentCursor::valid ( ) const

inlinenoexcept

Returns

True when the cursor points at a valid component payload, tag, or field.

write_bytes()

ComponentWriteResult gaia::ecs::ComponentCursor::write_bytes ( const void *  data, uint32_t  byteCount  )

inlinenoexcept

Writes exact bytes to the current cursor position.

This is the cursor write path for runtime component data. It performs no type conversion and requires byteCount to match the current cursor scope size. Use field navigation to choose the address being written. Successful writes finish the root component write, so normal chunk write tracking and OnSet observers run.

Parameters

data	Bytes to copy. Must be non-null when byteCount is non-zero.
byteCount	Number of bytes to copy. Returns Ok when bytes were copied, otherwise the reason the write failed.

---

The documentation for this struct was generated from the following file:

• /home/runner/work/gaia-ecs/gaia-ecs/include/gaia/ecs/component_cursor.h