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.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
feat(replication): replicated declarations reach COMPONENT_META — RC11 N0 base
esengine8f1cea2bf787
diff --git a/sdk/src/component.generated.ts b/sdk/src/component.generated.tsindex 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.tsindex 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, Fiereturn 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?: ComponententityFields: 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.tsindex 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.tsnew file mode 100644index 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.cppindex 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.hppindex 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.hppindex 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.pyindex 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: {')