Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

feat(replication): replicated declarations reach COMPONENT_META — RC11 N0 base

esengine8f1cea2bf787
diff --git a/sdk/src/component.generated.ts b/sdk/src/component.generated.ts
index e13690b6b..969f9e03d 100644
--- a/sdk/src/component.generated.ts
+++ b/sdk/src/component.generated.ts
@@ -41,6 +41,14 @@ export interface ComponentMetaEntry {
entityFields: string[];
colorFields: string[];
animatableFields: string[];
+ /**
+ * Fields authored `replicated` at the C++ ES_PROPERTY site — the
+ * single source of truth for what the network replication layer
+ * syncs (RC11). Whole-field granularity; absent = nothing replicates.
+ */
+ replicatedFields?: string[];
+ /** Fields authored `skip_serialize` — runtime-only state scene serialization omits. */
+ skipSerializeFields?: string[];
fields?: Record<string, FieldMeta>;
}
@@ -560,6 +568,7 @@ export const COMPONENT_META: Record<string, ComponentMetaEntry> = {
entityFields: [],
colorFields: [],
animatableFields: ['position.x', 'position.y', 'position.z', 'rotation.z', 'scale.x', 'scale.y', 'scale.z'],
+ replicatedFields: ['position', 'rotation', 'scale'],
fields: {
position: { tooltip: "Local position in world units, relative to the parent." },
rotation: { tooltip: "Rotation about the Z axis, in degrees." },
@@ -656,6 +665,7 @@ export const COMPONENT_META: Record<string, ComponentMetaEntry> = {
entityFields: [],
colorFields: [],
animatableFields: [],
+ replicatedFields: ['linear', 'angular'],
},
};
diff --git a/sdk/src/component.ts b/sdk/src/component.ts
index 1f3b7aa91..a01907f71 100644
--- a/sdk/src/component.ts
+++ b/sdk/src/component.ts
@@ -93,6 +93,12 @@ export interface ComponentMetadata {
fields?: Record<string, FieldMeta>;
/** Keyframeable fields (Sequencer tracks); auto-derived from numeric fields if omitted. */
animatableFields?: string[];
+ /**
+ * Fields the network replication layer syncs (RC11). Whole-field granularity;
+ * omitted = the component never replicates. Builtins author this at the C++
+ * ES_PROPERTY site (`replicated`) instead — same single-source rule as fieldMeta.
+ */
+ replicatedFields?: string[];
/**
* Custom asset discovery for scene preload. Authoritative when present:
* `assetFields` are NOT walked for discovery (they still drive editor
@@ -146,6 +152,8 @@ export interface ComponentDef<T> {
readonly entityFields: readonly string[];
readonly colorKeys: readonly string[];
readonly animatableFields: readonly string[];
+ /** Fields the replication layer syncs; empty = never replicates. See {@link ComponentMetadata.replicatedFields}. */
+ readonly replicatedFields: readonly string[];
readonly fieldMeta: Readonly<Record<string, FieldMeta>>;
readonly discoverAssets?: (data: Record<string, unknown>) => AssetRef[];
/** Runtime-only: omitted from scene serialization. See {@link ComponentMetadata.transient}. */
@@ -213,6 +221,14 @@ function createComponentDef<T extends object>(
): ComponentDef<T> {
const keyInfo = classifyKeys(defaults);
const defaultsRec = defaults as Record<string, unknown>;
+ // A replicated name that matches no field would silently sync nothing — the
+ // drift class this metadata exists to kill, so it fails loud (same spirit as
+ // EHT rejecting a malformed known annotation).
+ for (const f of metadata?.replicatedFields ?? []) {
+ if (!(f in defaultsRec)) {
+ throw new Error(`Component "${name}": replicatedFields names unknown field "${f}"`);
+ }
+ }
return {
_id: componentId(name),
_name: name,
@@ -223,6 +239,7 @@ function createComponentDef<T extends object>(
entityFields: metadata?.entityFields ?? [],
colorKeys: detectColorKeys(defaults),
animatableFields: metadata?.animatableFields ?? numericAnimatableFields(defaults),
+ replicatedFields: metadata?.replicatedFields ?? [],
fieldMeta: metadata?.fields ?? {},
discoverAssets: metadata?.discoverAssets,
transient: metadata?.transient ?? false,
@@ -353,6 +370,8 @@ export interface BuiltinComponentDef<T> {
readonly entityFields: readonly string[];
readonly colorKeys: readonly string[];
readonly animatableFields: readonly string[];
+ /** Fields authored `replicated` at the C++ ES_PROPERTY site (via COMPONENT_META). */
+ readonly replicatedFields: readonly string[];
readonly fieldMeta: Readonly<Record<string, FieldMeta>>;
readonly discoverAssets?: (data: Record<string, unknown>) => AssetRef[];
/** Runtime-only: omitted from scene serialization. See {@link ComponentMetadata.transient}. */
@@ -426,6 +445,15 @@ export function getComponentFieldMeta(name: string): Readonly<Record<string, Fie
return getComponent(name)?.fieldMeta ?? {};
}
+/**
+ * The fields the replication layer syncs for a component — builtin (C++
+ * `replicated` annotation) and user (`replicatedFields` metadata) through one
+ * accessor. Empty = the component never replicates.
+ */
+export function getReplicatedFields(name: string): readonly string[] {
+ return getComponent(name)?.replicatedFields ?? [];
+}
+
/**
* Per-field merge of two FieldMeta maps: `override` wins key-by-key *within* a field
* (not whole-field replacement), so a builtin can author min/tooltip at the C++
@@ -497,6 +525,7 @@ export function defineBuiltin<T>(name: string, defaults: T, metadata?: Component
entityFields: metadata?.entityFields ?? meta?.entityFields ?? [],
colorKeys: meta?.colorFields ?? detectColorKeys(defaults),
animatableFields: meta?.animatableFields ?? [],
+ replicatedFields: meta?.replicatedFields ?? [],
fieldMeta: mergeFieldMeta(meta?.fields ?? {}, metadata?.fields ?? {}),
discoverAssets: metadata?.discoverAssets,
// Builtins declare transience via the defineBuiltin metadata arg for now;
diff --git a/sdk/src/core-runtime.ts b/sdk/src/core-runtime.ts
index c3a076805..b0f78b7d0 100644
--- a/sdk/src/core-runtime.ts
+++ b/sdk/src/core-runtime.ts
@@ -69,6 +69,7 @@ export {
registerComponent,
getComponent,
getComponentFieldMeta,
+ getReplicatedFields,
getComponentRegistry,
getAllRegisteredComponents,
getUserComponents,
diff --git a/sdk/tests/replicated-fields.test.ts b/sdk/tests/replicated-fields.test.ts
new file mode 100644
index 000000000..af622f4bd
--- /dev/null
+++ b/sdk/tests/replicated-fields.test.ts
@@ -0,0 +1,58 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file Replication declaration single-sourcing (RC11 N0): `replicated` is
+ * authored at the C++ ES_PROPERTY site, flows through
+ * COMPONENT_META.replicatedFields, and user components declare the same
+ * thing via defineComponent metadata — one accessor over both.
+ */
+import { describe, it, expect } from 'vitest';
+import {
+ defineComponent,
+ getReplicatedFields,
+ clearUserComponents,
+} from '../src/component';
+import { COMPONENT_META } from '../src/component.generated';
+
+describe('replicated single-source (builtins)', () => {
+ it('Transform authors its local pose as replicated at the ES_PROPERTY site', () => {
+ expect(COMPONENT_META.Transform.replicatedFields).toEqual(['position', 'rotation', 'scale']);
+ expect(getReplicatedFields('Transform')).toEqual(['position', 'rotation', 'scale']);
+ });
+
+ it('Velocity replicates both fields', () => {
+ expect(getReplicatedFields('Velocity')).toEqual(['linear', 'angular']);
+ });
+
+ it('an unannotated builtin replicates nothing', () => {
+ expect(COMPONENT_META.Sprite.replicatedFields).toBeUndefined();
+ expect(getReplicatedFields('Sprite')).toEqual([]);
+ });
+
+ it('computed world-space fields are not replicated', () => {
+ expect(getReplicatedFields('Transform')).not.toContain('worldPosition');
+ });
+});
+
+describe('replicated metadata (user components)', () => {
+ it('defineComponent surfaces replicatedFields through the same accessor', () => {
+ clearUserComponents();
+ defineComponent('NetHealth', { hp: 100, maxHp: 100, lastHitBy: 0 }, {
+ replicatedFields: ['hp', 'maxHp'],
+ });
+ expect(getReplicatedFields('NetHealth')).toEqual(['hp', 'maxHp']);
+ clearUserComponents();
+ });
+
+ it('a replicated name that matches no field fails loud', () => {
+ clearUserComponents();
+ expect(() =>
+ defineComponent('NetTypo', { hp: 100 }, { replicatedFields: ['hpp'] }),
+ ).toThrow(/unknown field "hpp"/);
+ clearUserComponents();
+ });
+
+ it('an unknown component name replicates nothing', () => {
+ expect(getReplicatedFields('NoSuchComponent')).toEqual([]);
+ });
+});
diff --git a/src/esengine/bindings/EditorAPI.generated.cpp b/src/esengine/bindings/EditorAPI.generated.cpp
index 02e14fe14..3523530fe 100644
--- a/src/esengine/bindings/EditorAPI.generated.cpp
+++ b/src/esengine/bindings/EditorAPI.generated.cpp
@@ -2,10 +2,10 @@
* @file EditorAPI.generated.cpp
* @brief Auto-generated editor API with string-dispatched component access
* @details Generated by EHT - DO NOT EDIT
- * @schema_hash f2224cd6bc00e0ff
+ * @schema_hash 9336a63ec9fd21a6
*/
-#define ES_EDITOR_API_SCHEMA_HASH "f2224cd6bc00e0ff"
+#define ES_EDITOR_API_SCHEMA_HASH "9336a63ec9fd21a6"
#include <emscripten/bind.h>
#include <string>
diff --git a/src/esengine/ecs/components/Transform.hpp b/src/esengine/ecs/components/Transform.hpp
index 22a00a3a1..9010a8be3 100644
--- a/src/esengine/ecs/components/Transform.hpp
+++ b/src/esengine/ecs/components/Transform.hpp
@@ -40,13 +40,13 @@ namespace esengine::ecs {
*/
ES_COMPONENT()
struct Transform {
- ES_PROPERTY(animatable, anim_override, tooltip="Local position in world units, relative to the parent.")
+ ES_PROPERTY(animatable, anim_override, replicated, tooltip="Local position in world units, relative to the parent.")
glm::vec3 position{0.0f, 0.0f, 0.0f};
- ES_PROPERTY(animatable, anim_override, tooltip="Rotation about the Z axis, in degrees.")
+ ES_PROPERTY(animatable, anim_override, replicated, tooltip="Rotation about the Z axis, in degrees.")
glm::quat rotation{1.0f, 0.0f, 0.0f, 0.0f};
- ES_PROPERTY(animatable, anim_override, tooltip="Local scale per axis (1 = original size; negative flips).")
+ ES_PROPERTY(animatable, anim_override, replicated, tooltip="Local scale per axis (1 = original size; negative flips).")
glm::vec3 scale{1.0f, 1.0f, 1.0f};
ES_PROPERTY(readonly)
diff --git a/src/esengine/ecs/components/Velocity.hpp b/src/esengine/ecs/components/Velocity.hpp
index 3f4514672..08349898d 100644
--- a/src/esengine/ecs/components/Velocity.hpp
+++ b/src/esengine/ecs/components/Velocity.hpp
@@ -38,11 +38,11 @@ namespace esengine::ecs {
ES_COMPONENT()
struct Velocity {
/** @brief Linear velocity (units per second) */
- ES_PROPERTY()
+ ES_PROPERTY(replicated)
glm::vec3 linear{0.0f};
/** @brief Angular velocity (radians per second) */
- ES_PROPERTY()
+ ES_PROPERTY(replicated)
glm::vec3 angular{0.0f};
/** @brief Default constructor (zero velocity) */
diff --git a/tools/eht/generators/metadata.py b/tools/eht/generators/metadata.py
index 087c7a9f6..879e8f0a4 100644
--- a/tools/eht/generators/metadata.py
+++ b/tools/eht/generators/metadata.py
@@ -149,6 +149,12 @@ class MetadataGenerator:
out.append((prop.name, convert_default_ts(shadow, self.types, self._enum_values)))
return out
+ def _get_replicated_fields(self, comp: Component) -> List[str]:
+ return [p.name for p in comp.properties if 'replicated' in p.annotations]
+
+ def _get_skip_serialize_fields(self, comp: Component) -> List[str]:
+ return [p.name for p in comp.properties if 'skip_serialize' in p.annotations]
+
def _get_animatable_fields(self, comp: Component) -> List[str]:
fields = []
for prop in comp.properties:
@@ -297,6 +303,14 @@ class MetadataGenerator:
' entityFields: string[];',
' colorFields: string[];',
' animatableFields: string[];',
+ ' /**',
+ ' * Fields authored `replicated` at the C++ ES_PROPERTY site — the',
+ ' * single source of truth for what the network replication layer',
+ ' * syncs (RC11). Whole-field granularity; absent = nothing replicates.',
+ ' */',
+ ' replicatedFields?: string[];',
+ ' /** Fields authored `skip_serialize` — runtime-only state scene serialization omits. */',
+ ' skipSerializeFields?: string[];',
' fields?: Record<string, FieldMeta>;',
'}',
'',
@@ -362,6 +376,15 @@ class MetadataGenerator:
else:
lines.append(' animatableFields: [],')
+ replicated = self._get_replicated_fields(comp)
+ if replicated:
+ parts = ', '.join(f"'{f}'" for f in replicated)
+ lines.append(f' replicatedFields: [{parts}],')
+ skip_serialize = self._get_skip_serialize_fields(comp)
+ if skip_serialize:
+ parts = ', '.join(f"'{f}'" for f in skip_serialize)
+ lines.append(f' skipSerializeFields: [{parts}],')
+
field_meta = self._get_field_meta(comp)
if field_meta:
lines.append(' fields: {')