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(editor): Marker custom properties + a key→value map inspector field

yhhee265f559a4a
diff --git a/desktop/src/engine/SceneCommands.ts b/desktop/src/engine/SceneCommands.ts
index 70928a8a2..370b8f2b3 100644
--- a/desktop/src/engine/SceneCommands.ts
+++ b/desktop/src/engine/SceneCommands.ts
@@ -155,6 +155,10 @@ export function toModelValue(
case 'curve':
case 'dimension':
return value; // a structural object ({ stops/keys: [...] }, { value, unit }) — stored as-is
+ case 'map':
+ // An arbitrary string→string map (Marker custom properties) — cloned so the stored
+ // object doesn't alias the editor's working copy.
+ return { ...(value as Record<string, string>) };
default:
return value;
}
diff --git a/desktop/src/engine/ViewportController.ts b/desktop/src/engine/ViewportController.ts
index 1f55a924b..9d5120f3f 100644
--- a/desktop/src/engine/ViewportController.ts
+++ b/desktop/src/engine/ViewportController.ts
@@ -663,13 +663,17 @@ export const ViewportController = {
/** Screen-space position of a Marker's pin (its Transform world position → canvas px),
* and its `type` label, or null when off-camera/removed. */
- getMarkerGizmo(id: EntityId): { cx: number; cy: number; type: string } | null {
+ getMarkerGizmo(id: EntityId): { cx: number; cy: number; type: string; properties: Record<string, string> } | null {
const world = EngineHost.world;
if (!world || !world.valid(id) || !world.has(id, Marker) || !world.has(id, Transform)) return null;
const t = world.get(id, Transform);
- const m = world.get(id, Marker) as { type?: string };
+ const m = world.get(id, Marker) as { type?: string; properties?: Record<string, string> };
const p = this.worldToClient(t.worldPosition.x, t.worldPosition.y);
- return p ? { cx: p.x, cy: p.y, type: typeof m.type === 'string' ? m.type : '' } : null;
+ return p ? {
+ cx: p.x, cy: p.y,
+ type: typeof m.type === 'string' ? m.type : '',
+ properties: m.properties && typeof m.properties === 'object' ? m.properties : {},
+ } : null;
},
/** Ids of entities carrying ANY collider (box/circle/capsule/segment/polygon/chain) —
diff --git a/desktop/src/engine/schema.ts b/desktop/src/engine/schema.ts
index 70a876056..527402f47 100644
--- a/desktop/src/engine/schema.ts
+++ b/desktop/src/engine/schema.ts
@@ -257,6 +257,8 @@ export interface UserFieldMeta {
bitmask?: { bits?: number; source?: string };
gradient?: boolean;
curve?: boolean;
+ /** Render as a key→value string map editor (arbitrary custom properties). */
+ map?: boolean;
min?: number;
max?: number;
step?: number;
@@ -399,6 +401,7 @@ export function fieldMetaFor(compType: string, key: string): UserFieldMeta | nul
bitmask: fromDef.bitmask,
gradient: fromDef.gradient,
curve: fromDef.curve,
+ map: fromDef.map,
min: fromDef.min,
max: fromDef.max,
step: fromDef.step,
@@ -551,6 +554,13 @@ function fieldFor(
} else if (meta?.curve) {
const c = value && typeof value === 'object' && Array.isArray((value as CurveValue).keys) ? (value as CurveValue) : { keys: [] };
field = { key, label: prettyLabel(key), type: 'curve', value: c };
+ } else if (meta?.map) {
+ // Arbitrary string→string map (Marker.properties). Normalize every value to a string
+ // so the editor never chokes on a stray non-string import.
+ const raw = value && typeof value === 'object' && !Array.isArray(value) ? (value as Record<string, unknown>) : {};
+ const m: Record<string, string> = {};
+ for (const k of Object.keys(raw)) m[k] = String(raw[k]);
+ field = { key, label: prettyLabel(key), type: 'map', value: m };
} else if (meta?.bitmask) {
field = { key, label: prettyLabel(key), type: 'flags', value: Number(value) || 0, options: bitmaskOptions(meta.bitmask) };
} else if (meta?.flags && meta.flags.length) {
diff --git a/desktop/src/flipbook/animClipInspectorModel.ts b/desktop/src/flipbook/animClipInspectorModel.ts
index 04b3e780a..e8b75d942 100644
--- a/desktop/src/flipbook/animClipInspectorModel.ts
+++ b/desktop/src/flipbook/animClipInspectorModel.ts
@@ -10,7 +10,7 @@
* inspector, no bespoke property panel.
*/
import type { AnimClipAssetData } from 'esengine';
-import type { InspectorComponent, InspectorFieldType, GradientValue, CurveValue, DimensionValue } from '@/types';
+import type { InspectorComponent, InspectorFieldType, GradientValue, CurveValue, DimensionValue, MapValue } from '@/types';
import { AnimClipCommands } from './AnimClipCommands';
import { t } from '@/i18n';
@@ -55,7 +55,7 @@ export function buildAnimClipComponents(asset: AnimClipAssetData): InspectorComp
/** A FieldWrite routing inspector edits to the open AnimClipDocument via AnimClipCommands. */
export function makeAnimClipWrite() {
- return (key: string, _type: InspectorFieldType, value: number | boolean | string | number[] | GradientValue | CurveValue | DimensionValue): void => {
+ return (key: string, _type: InspectorFieldType, value: number | boolean | string | number[] | GradientValue | CurveValue | DimensionValue | MapValue): void => {
switch (key) {
case 'fps':
AnimClipCommands.setFps(value as number);
diff --git a/desktop/src/i18n/messages/details.ts b/desktop/src/i18n/messages/details.ts
index cce3ed46b..8bf803279 100644
--- a/desktop/src/i18n/messages/details.ts
+++ b/desktop/src/i18n/messages/details.ts
@@ -11,6 +11,10 @@ export const detailsMessages = defineMessages({
'det.noMatch': { en: 'No match', zh: '无匹配项' },
'det.none': { en: 'None', zh: '无' },
'det.noneOption': { en: '(none)', zh: '(无)' },
+ 'det.mapKey': { en: 'key', zh: '键' },
+ 'det.mapValue': { en: 'value', zh: '值' },
+ 'det.mapAdd': { en: 'Add property', zh: '添加属性' },
+ 'det.mapRemove': { en: 'Remove property', zh: '删除属性' },
'det.everything': { en: 'Everything', zh: '全部' },
'det.nothing': { en: 'Nothing', zh: '清空' },
'det.unitAria': { en: 'unit', zh: '单位' },
diff --git a/desktop/src/main.tsx b/desktop/src/main.tsx
index b9a3b2503..59c4e92a7 100644
--- a/desktop/src/main.tsx
+++ b/desktop/src/main.tsx
@@ -152,7 +152,7 @@ if (new URLSearchParams(location.search).has('automation')) {
* derived projection (`src == null`) — verifies object-group → Marker convergence. */
liveMarkers: () => ViewportController.markerIds().map((rt) => {
const g = ViewportController.getMarkerGizmo(rt);
- return { rt, type: g?.type ?? null, src: SceneModel.sourceFor(rt) ?? null };
+ return { rt, type: g?.type ?? null, properties: g?.properties ?? {}, src: SceneModel.sourceFor(rt) ?? null };
}),
/** Probe a layer's resolved tile-collision overlay — the SAME pieces the viewport
* draws + Play spawns. Returns null if nothing resolves; else piece counts by kind.
diff --git a/desktop/src/material/materialInspectorModel.ts b/desktop/src/material/materialInspectorModel.ts
index e477b4c61..bd8c55d45 100644
--- a/desktop/src/material/materialInspectorModel.ts
+++ b/desktop/src/material/materialInspectorModel.ts
@@ -13,7 +13,7 @@
* std140 layout; this is the editor view of the declarations.
*/
import { BlendMode, CullMode, Material, builtinShaderTemplate, type MaterialAssetData, type UniformValue } from 'esengine';
-import type { InspectorComponent, InspectorField, InspectorFieldType, EnumOption, GradientValue, CurveValue, DimensionValue } from '@/types';
+import type { InspectorComponent, InspectorField, InspectorFieldType, EnumOption, GradientValue, CurveValue, DimensionValue, MapValue } from '@/types';
import { t } from '@/i18n';
import { MaterialDocument } from './MaterialDocument';
import { reflectEsshader, type ShaderParam, type ShaderReflection } from './shaderReflect';
@@ -265,7 +265,7 @@ function fieldValueToAsset(param: ShaderParam, value: number | boolean | string
export function makeMaterialWrite(ctx: MaterialContext) {
// The value union matches FieldRow's edit callback; materials only ever emit
// number / boolean / string / number[] (no gradient/curve), so the cast below is safe.
- return (key: string, _type: InspectorFieldType, value: number | boolean | string | number[] | GradientValue | CurveValue | DimensionValue): void => {
+ return (key: string, _type: InspectorFieldType, value: number | boolean | string | number[] | GradientValue | CurveValue | DimensionValue | MapValue): void => {
if (RENDER_STATE_KEYS.has(key)) {
MaterialDocument.edit(`Set ${key}`, (d) => {
(d as unknown as Record<string, unknown>)[key] = value;
diff --git a/desktop/src/panels/Details.tsx b/desktop/src/panels/Details.tsx
index 6cedb7b08..b78ed7cb1 100644
--- a/desktop/src/panels/Details.tsx
+++ b/desktop/src/panels/Details.tsx
@@ -104,7 +104,7 @@ import { SearchField } from '@/components/SearchField';
import { Select } from '@/components/Select';
import { Segmented, type SegmentedOption } from '@/components/Segmented';
import { AddComponentMenu } from '@/components/AddComponentMenu';
-import type { InspectorComponent, InspectorField, InspectorFieldValue, EntityId, NodeKind, EnumOption, AssetType, GradientValue, GradientStop, CurveValue, CurveKey, DimensionValue, InspectSource } from '@/types';
+import type { InspectorComponent, InspectorField, InspectorFieldValue, EntityId, NodeKind, EnumOption, AssetType, GradientValue, GradientStop, CurveValue, CurveKey, DimensionValue, MapValue, InspectSource } from '@/types';
const AXES = ['x', 'y', 'z', 'w'];
@@ -754,6 +754,60 @@ function sampleStops(stops: GradientStop[], t: number): GradientStop['color'] {
return { ...last.color };
}
+// A key→value string-map editor (Marker.properties): one row per pair (editable key +
+// value + delete), plus an add button. Arbitrary Tiled-style custom properties. Each edit
+// rebuilds the whole map through the standard field write door (one undo step per change).
+function MapControl({
+ value,
+ onBegin,
+ onEnd,
+ onChange,
+}: ControlGesture & { value: MapValue; onChange: (v: MapValue) => void }) {
+ const entries = Object.entries(value);
+ const commit = (next: MapValue) => { onBegin?.(); onChange(next); onEnd?.(); };
+ const rename = (oldKey: string, raw: string) => {
+ const newKey = raw.trim();
+ // No-op on unchanged / blank / colliding keys (the input reverts on re-render).
+ if (newKey === oldKey || newKey === '' || newKey in value) return;
+ const next: MapValue = {};
+ for (const [k, v] of Object.entries(value)) next[k === oldKey ? newKey : k] = v;
+ commit(next);
+ };
+ const setVal = (k: string, v: string) => { if (value[k] !== v) commit({ ...value, [k]: v }); };
+ const remove = (k: string) => { const next = { ...value }; delete next[k]; commit(next); };
+ const add = () => {
+ let key = 'key';
+ for (let n = 2; key in value; n++) key = `key${n}`;
+ commit({ ...value, [key]: '' });
+ };
+ const blurOnEnter = (e: React.KeyboardEvent<HTMLInputElement>) => {
+ if (e.key === 'Enter') e.currentTarget.blur();
+ if (e.key === 'Escape') { e.currentTarget.value = e.currentTarget.defaultValue; e.currentTarget.blur(); }
+ };
+ return (
+ <div className="map-field">
+ {entries.map(([k, v]) => (
+ <div key={k} className="map-row">
+ <input
+ className="map-key" defaultValue={k} aria-label={t('det.mapKey')} placeholder={t('det.mapKey')}
+ onKeyDown={blurOnEnter} onBlur={(e) => rename(k, e.target.value)}
+ />
+ <input
+ className="map-val" defaultValue={v} aria-label={t('det.mapValue')} placeholder={t('det.mapValue')}
+ onKeyDown={blurOnEnter} onBlur={(e) => setVal(k, e.target.value)}
+ />
+ <button type="button" className="map-del" title={t('det.mapRemove')} onClick={() => remove(k)}>
+ <X size={12} />
+ </button>
+ </div>
+ ))}
+ <button type="button" className="map-add" onClick={add}>
+ <Plus size={12} /> {t('det.mapAdd')}
+ </button>
+ </div>
+ );
+}
+
// A color-over-life gradient editor: a preview bar with draggable stops; click the
// bar to add a stop, select one to edit its color (the themed picker) or delete it.
// Empty ⇒ the particle falls back to start/end + easing (the runtime bake skips it).
@@ -1090,7 +1144,7 @@ export function AssetControl({
// A field write override (the live "Game" inspector routes edits to the realm
// instead of the undoable SceneCommands path). When set, gestures are no-ops.
-type FieldWrite = (key: string, type: InspectorField['type'], value: number | boolean | string | number[] | GradientValue | CurveValue | DimensionValue) => void;
+type FieldWrite = (key: string, type: InspectorField['type'], value: number | boolean | string | number[] | GradientValue | CurveValue | DimensionValue | MapValue) => void;
// The write primitives for one field, shared by FieldRow and the compound
// BoxSidesControl so both commit through the identical door: an edit fans out to
@@ -1099,7 +1153,7 @@ type FieldWrite = (key: string, type: InspectorField['type'], value: number | bo
// instead, where gestures are no-ops.
function fieldWriter(entities: EntityId[], comp: string, field: InspectorField, write?: FieldWrite) {
const ranged = field.min != null || field.max != null;
- const apply = (value: number | boolean | string | number[] | GradientValue | CurveValue | DimensionValue) => {
+ const apply = (value: number | boolean | string | number[] | GradientValue | CurveValue | DimensionValue | MapValue) => {
let v = value;
if (ranged && typeof v === 'number') {
if (field.min != null) v = Math.max(field.min, v);
@@ -1378,6 +1432,9 @@ function FieldRow({ entities, comp, field, write }: { entities: EntityId[]; comp
case 'curve':
control = <CurveControl value={field.value as CurveValue} onBegin={begin} onEnd={end} onChange={apply} />;
break;
+ case 'map':
+ control = <MapControl value={field.value as MapValue} onBegin={begin} onEnd={end} onChange={apply} />;
+ break;
case 'asset':
control = (
<AssetControl
diff --git a/desktop/src/theme/inspector.css b/desktop/src/theme/inspector.css
index 3372a1747..600a43a20 100644
--- a/desktop/src/theme/inspector.css
+++ b/desktop/src/theme/inspector.css
@@ -396,3 +396,44 @@
font-size: var(--fs-2xs);
font-variant-numeric: tabular-nums;
}
+
+/* Map (key→value) field editor — Marker custom properties. One row per pair. */
+.map-field { display: flex; flex-direction: column; gap: 4px; width: 100%; }
+.map-row { display: grid; grid-template-columns: minmax(0, 1fr) minmax(0, 1.4fr) auto; gap: 4px; align-items: center; }
+.map-key,
+.map-val {
+ min-width: 0;
+ height: 22px;
+ padding: 0 6px;
+ background: var(--srf-3);
+ border: 1px solid var(--border-line);
+ border-radius: var(--r-xs);
+ color: var(--text);
+ font-size: var(--fs-xs);
+}
+.map-key { color: var(--text-dim); }
+.map-key:focus,
+.map-val:focus { border-color: var(--acc); box-shadow: 0 0 0 2px var(--acc-soft); outline: none; }
+.map-del {
+ display: grid;
+ place-items: center;
+ width: 22px;
+ height: 22px;
+ color: var(--text-faint);
+ border-radius: var(--r-xs);
+ transition: color var(--t-fast), background var(--t-fast);
+}
+.map-del:hover { color: var(--danger, #e5484d); background: var(--srf-4); }
+.map-add {
+ display: inline-flex;
+ align-items: center;
+ gap: 4px;
+ align-self: flex-start;
+ padding: 3px 7px;
+ font-size: var(--fs-2xs);
+ color: var(--acc-hi);
+ border: 1px dashed var(--border-line);
+ border-radius: var(--r-xs);
+ transition: border-color var(--t-fast), background var(--t-fast);
+}
+.map-add:hover { border-color: var(--acc); background: var(--acc-soft); }
diff --git a/desktop/src/timeline/keyframeInspectorModel.ts b/desktop/src/timeline/keyframeInspectorModel.ts
index 181c93d16..5a14ba6bf 100644
--- a/desktop/src/timeline/keyframeInspectorModel.ts
+++ b/desktop/src/timeline/keyframeInspectorModel.ts
@@ -11,7 +11,7 @@
* TimelineCommands (one undo step each).
*/
import { InterpType, type TimelineAsset } from 'esengine';
-import type { InspectorComponent, InspectorFieldType, GradientValue, CurveValue, DimensionValue } from '@/types';
+import type { InspectorComponent, InspectorFieldType, GradientValue, CurveValue, DimensionValue, MapValue } from '@/types';
import { buildTimelineRows, findChannel, type ChannelRef } from './timelineView';
import { TimelineCommands } from './TimelineCommands';
import { TimelineDocument } from './TimelineDocument';
@@ -61,7 +61,7 @@ export function buildKeyframeComponents(asset: TimelineAsset, selectedKey: strin
}
export function makeKeyframeWrite(selectedKey: string) {
- return (key: string, _type: InspectorFieldType, value: number | boolean | string | number[] | GradientValue | CurveValue | DimensionValue): void => {
+ return (key: string, _type: InspectorFieldType, value: number | boolean | string | number[] | GradientValue | CurveValue | DimensionValue | MapValue): void => {
const asset = TimelineDocument.asset;
if (!asset) return;
const r = resolve(asset, selectedKey);
diff --git a/desktop/src/timeline/timelineInspectorModel.ts b/desktop/src/timeline/timelineInspectorModel.ts
index 2ffd2a71a..ae7ff8b36 100644
--- a/desktop/src/timeline/timelineInspectorModel.ts
+++ b/desktop/src/timeline/timelineInspectorModel.ts
@@ -12,7 +12,7 @@
*/
import type { TimelineAsset } from 'esengine';
import { WrapMode } from 'esengine';
-import type { InspectorComponent, InspectorFieldType, GradientValue, CurveValue, DimensionValue } from '@/types';
+import type { InspectorComponent, InspectorFieldType, GradientValue, CurveValue, DimensionValue, MapValue } from '@/types';
import { TimelineCommands } from './TimelineCommands';
import { TimelineDocument } from './TimelineDocument';
import { t } from '@/i18n';
@@ -43,7 +43,7 @@ export function buildTimelineComponents(asset: TimelineAsset, fps: number): Insp
/** A FieldWrite routing timeline clip-setting edits to the document/commands. */
export function makeTimelineWrite() {
- return (key: string, _type: InspectorFieldType, value: number | boolean | string | number[] | GradientValue | CurveValue | DimensionValue): void => {
+ return (key: string, _type: InspectorFieldType, value: number | boolean | string | number[] | GradientValue | CurveValue | DimensionValue | MapValue): void => {
switch (key) {
case 'duration':
TimelineCommands.setDuration(value as number);
diff --git a/desktop/src/types.ts b/desktop/src/types.ts
index f45dd8aa2..5cb0436ba 100644
--- a/desktop/src/types.ts
+++ b/desktop/src/types.ts
@@ -42,6 +42,7 @@ export type InspectorFieldType =
| 'flags' // an int bitmask, shown as a multi-select of its bits
| 'gradient' // a color-over-life gradient ({ stops: [...] })
| 'curve' // a scalar over-life curve ({ keys: [...] })
+ | 'map' // an arbitrary key→value string map (Marker.properties) — Tiled-style custom props
| 'dimension' // a CSS-style length ({ value, unit }) — UINode box/inset fields
| 'sides' // a four-edge box ({ left, top, right, bottom }) — FlexContainer/TextInput padding
| 'asset' // a texture/material/font/... ref (@uuid: string, or 0 for none)
@@ -79,6 +80,9 @@ export interface DimensionValue {
unit: number;
}
+/** A `map` field's value — an arbitrary key→value string map (Marker custom properties). */
+export type MapValue = Record<string, string>;
+
export type InspectorFieldValue =
| number
| boolean
@@ -88,7 +92,8 @@ export type InspectorFieldValue =
| [number, number, number, number]
| GradientValue
| CurveValue
- | DimensionValue;
+ | DimensionValue
+ | MapValue;
export interface InspectorField {
/** key in the component data object */
@@ -172,7 +177,7 @@ export interface InspectSource {
subscribe: (onChange: () => void) => () => void;
getRevision: () => number;
build: () => InspectorComponent[];
- write: (key: string, type: InspectorFieldType, value: number | boolean | string | number[] | GradientValue | CurveValue | DimensionValue) => void;
+ write: (key: string, type: InspectorFieldType, value: number | boolean | string | number[] | GradientValue | CurveValue | DimensionValue | MapValue) => void;
/**
* When true this is an explicit sub-object selection (a keyframe, a track) and
* OVERRIDES the entity/asset inspector. Default (false) is a fallback — shown
diff --git a/examples/tilemap-demo/assets/maps/level.tmj b/examples/tilemap-demo/assets/maps/level.tmj
index 59e7b952a..248020dc1 100644
--- a/examples/tilemap-demo/assets/maps/level.tmj
+++ b/examples/tilemap-demo/assets/maps/level.tmj
@@ -2455,7 +2455,7 @@
"id":5,
"name":"spawns",
"objects":[
- {"id":1,"name":"player-spawn","type":"spawn","point":true,"x":90,"y":150,"width":0,"height":0,"rotation":0,"visible":true,"properties":[]},
+ {"id":1,"name":"player-spawn","type":"spawn","point":true,"x":90,"y":150,"width":0,"height":0,"rotation":0,"visible":true,"properties":[{"name":"team","type":"string","value":"blue"},{"name":"facing","type":"string","value":"right"}]},
{"id":2,"name":"enemy-spawn","type":"enemy","point":true,"x":400,"y":110,"width":0,"height":0,"rotation":0,"visible":true,"properties":[]},
{"id":3,"name":"checkpoint","type":"checkpoint","point":true,"x":260,"y":250,"width":0,"height":0,"rotation":0,"visible":true,"properties":[]}
],
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 51c8d0fa8..679518835 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -2528,6 +2528,7 @@ enumSource: string | undefined
flags: readonly { label: string; value: number; }[] | undefined
gradient: boolean | undefined
label: string | undefined
+map: boolean | undefined
max: number | undefined
min: number | undefined
slider: boolean | undefined
@@ -3625,6 +3626,7 @@ ComponentDef<MarkerData>
## MarkerData — interface
```
+properties: Record<string, string>
type: string
```
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index a00403c30..ae465faed 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -2523,6 +2523,7 @@ enumSource: string | undefined
flags: readonly { label: string; value: number; }[] | undefined
gradient: boolean | undefined
label: string | undefined
+map: boolean | undefined
max: number | undefined
min: number | undefined
slider: boolean | undefined
@@ -3620,6 +3621,7 @@ ComponentDef<MarkerData>
## MarkerData — interface
```
+properties: Record<string, string>
type: string
```
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 3a67668ef..d791895dd 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -2523,6 +2523,7 @@ enumSource: string | undefined
flags: readonly { label: string; value: number; }[] | undefined
gradient: boolean | undefined
label: string | undefined
+map: boolean | undefined
max: number | undefined
min: number | undefined
slider: boolean | undefined
@@ -3627,6 +3628,7 @@ ComponentDef<MarkerData>
## MarkerData — interface
```
+properties: Record<string, string>
type: string
```
diff --git a/sdk/src/component.ts b/sdk/src/component.ts
index 28911423c..88a2f07bb 100644
--- a/sdk/src/component.ts
+++ b/sdk/src/component.ts
@@ -63,6 +63,11 @@ export interface FieldMeta {
gradient?: boolean;
/** Render as a scalar over-life curve editor (the field value is `{ keys: [...] }`). */
curve?: boolean;
+ /** Render as a key→value string map editor (the field value is `Record<string,string>`)
+ * — arbitrary user properties (e.g. a Marker's gameplay data), like Tiled's custom
+ * properties. Value-shape inference can't tell a property map from any other object,
+ * so a field must opt in here. */
+ map?: boolean;
/**
* Render as a bitmask whose bit LABELS are resolved by the editor (e.g. named
* collision layers from project settings) rather than fixed here. `bits` is the
@@ -840,6 +845,9 @@ export interface MarkerData {
* waypoint, pickup, door, trigger …). Free-form: the game defines the vocabulary.
* `Query(Marker)` then filters by `type`. */
type: string;
+ /** Arbitrary per-marker gameplay data (team, targetScene, event, …), like Tiled's
+ * custom object properties. Imported `.tmj` object properties land here too. */
+ properties: Record<string, string>;
}
/**
@@ -849,7 +857,11 @@ export interface MarkerData {
* parallel "object layer" structure — so it serializes, shows in the Inspector, and is
* `Query`-able like any component. The converged target for imported `.tmj` object groups.
*/
-export const Marker = defineComponent<MarkerData>('Marker', { type: '' });
+export const Marker = defineComponent<MarkerData>('Marker', { type: '', properties: {} }, {
+ // `properties` is an arbitrary string→string map — opt into the map editor (value-shape
+ // inference would otherwise drop it as an unknown object).
+ fields: { properties: { map: true } },
+});
export interface PostProcessVolumeData {
effects: {
diff --git a/sdk/src/tilemap/tilemapPlugin.ts b/sdk/src/tilemap/tilemapPlugin.ts
index c2f240fdc..1bddaaff0 100644
--- a/sdk/src/tilemap/tilemapPlugin.ts
+++ b/sdk/src/tilemap/tilemapPlugin.ts
@@ -523,9 +523,13 @@ export class TilemapPlugin implements Plugin {
// colliders — not projected here.
if (obj.gid === undefined) {
if (obj.shape === 'point') {
+ // Carry the Tiled object's custom properties (stringified) so
+ // imported markers hold the same per-object data as hand-authored.
+ const props: Record<string, string> = {};
+ for (const [k, v] of obj.properties) props[k] = String(v);
const markerChild = world.spawn(obj.name || `Marker_${obj.id}`);
world.insert(markerChild, Transform, { position: { x: obj.x, y: -obj.y, z: 0 } });
- world.insert(markerChild, Marker, { type: obj.type || '' });
+ world.insert(markerChild, Marker, { type: obj.type || '', properties: props });
world.insert(markerChild, RuntimeOnly, {});
world.setParent(markerChild, entity);
children.push(markerChild);
diff --git a/sdk/tests/marker-component.test.ts b/sdk/tests/marker-component.test.ts
index adca74e6f..a9227c435 100644
--- a/sdk/tests/marker-component.test.ts
+++ b/sdk/tests/marker-component.test.ts
@@ -27,30 +27,31 @@ function makeWorld(): World {
}
describe('Marker component', () => {
- it('is a registered component with a string `type` default', () => {
+ it('is a registered component with `type` + `properties` defaults', () => {
expect(Marker._name).toBe('Marker');
- expect(Marker._default).toEqual({ type: '' });
+ expect(Marker._default).toEqual({ type: '', properties: {} });
});
- it('serializes into the scene and round-trips its `type`', () => {
+ it('serializes into the scene and round-trips `type` + `properties`', () => {
const world = makeWorld();
const e = world.spawn('SpawnPoint');
world.insert(e, Transform, { position: { x: 3, y: 4, z: 0 } });
- world.insert(e, Marker, { type: 'player-spawn' });
+ world.insert(e, Marker, { type: 'player-spawn', properties: { team: 'red', delay: '2' } });
const scene = serializeScene(world, 'test');
const ent = scene.entities.find((n) => n.name === 'SpawnPoint')!;
const marker = ent.components.find((c) => c.type === 'Marker');
expect(marker).toBeTruthy();
expect((marker!.data as { type: string }).type).toBe('player-spawn');
+ expect((marker!.data as { properties: Record<string, string> }).properties).toEqual({ team: 'red', delay: '2' });
});
it('is query-able by its component id (distinct entities found)', () => {
const world = makeWorld();
const a = world.spawn('A');
- world.insert(a, Marker, { type: 'door' });
+ world.insert(a, Marker, { type: 'door', properties: {} });
const b = world.spawn('B');
- world.insert(b, Marker, { type: 'pickup' });
+ world.insert(b, Marker, { type: 'pickup', properties: {} });
world.spawn('C'); // no marker
const found = world.getEntitiesWithComponents([Marker]);