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 + Trigger Area — native object placement over any scene

yhh32a7e6b44032
diff --git a/desktop/src/components/icons.tsx b/desktop/src/components/icons.tsx
index f45338ee8..1707ba0d3 100644
--- a/desktop/src/components/icons.tsx
+++ b/desktop/src/components/icons.tsx
@@ -17,6 +17,7 @@ import {
Box,
Hexagon,
Link2,
+ MapPin,
type LucideIcon,
} from 'lucide-react';
import type { NodeKind, AssetType } from '@/types';
@@ -62,6 +63,7 @@ const COMPONENT_ICON: Record<string, LucideIcon> = {
Canvas: LayoutPanelTop,
SpineAnimation: PersonStanding,
RigidBody: Box,
+ Marker: MapPin,
};
export function componentGlyph(name: string): LucideIcon {
diff --git a/desktop/src/engine/entitySources.ts b/desktop/src/engine/entitySources.ts
index cca47ca8e..04115e064 100644
--- a/desktop/src/engine/entitySources.ts
+++ b/desktop/src/engine/entitySources.ts
@@ -11,7 +11,7 @@
* UI. (REARCH_ENTITY_CREATION E2.)
*/
import type { LucideIcon } from 'lucide-react';
-import { CircleDot, LayoutPanelTop, ToggleLeft, SlidersHorizontal, List, ChevronDown, SquareMousePointer, RectangleHorizontal, Box, Type, Image as ImageIcon, SquareDashed, ScrollText, AppWindow, TextCursorInput, Grid3x3 } from 'lucide-react';
+import { CircleDot, LayoutPanelTop, ToggleLeft, SlidersHorizontal, List, ChevronDown, SquareMousePointer, RectangleHorizontal, Box, Type, Image as ImageIcon, SquareDashed, ScrollText, AppWindow, TextCursorInput, Grid3x3, MapPin, Scan } from 'lucide-react';
import { BUILTIN_UI_PREFABS, BUILTIN_UI_WIDGET_NAMES, PREFAB_FORMAT_VERSION, getUserComponents, applyThemeToWorld, type PrefabData } from 'esengine';
import type { EntityId } from '@/types';
import { componentByName, componentDefaults, prettyLabel, componentCategory } from './schema';
@@ -262,6 +262,14 @@ export const ENTITY_SOURCES: EntitySource[] = [
// through this module at init; the action only runs on pick, long after load.
action: () => { void import('@/commands').then((m) => m.commands.run('tilemap.new')); },
},
+ // Object primitives — placed as real entities over any scene/background (the modern
+ // "object layer"): a Marker is a named point (spawn / waypoint / location, queried via
+ // `Query(Marker)`); a Trigger Area is a static SENSOR region (Transform + RigidBody +
+ // BoxCollider{isSensor} + Marker) that reuses the unified collider gizmo for shaping.
+ presetSource('marker', 'Marker', 'Common', MapPin,
+ ['Transform', ['Marker', { type: '' }]]),
+ presetSource('trigger-area', 'Trigger Area', 'Physics', Scan,
+ [['Transform', {}], ['RigidBody', { bodyType: 0 }], ['BoxCollider', { isSensor: true }], ['Marker', { type: '' }]]),
{
id: 'canvas',
label: 'Canvas',
@@ -297,7 +305,9 @@ export const ENTITY_SOURCES: EntitySource[] = [
* — the dynamic half of "cover all cases" (REARCH ENTITY_CREATION E4).
*/
export function userComponentSources(): EntitySource[] {
- return [...getUserComponents().keys()].map((name) => ({
+ // `Marker` is an engine component but ships a CURATED Create preset above (with its own
+ // icon + category), so drop it from the generic user-component list to avoid a duplicate.
+ return [...getUserComponents().keys()].filter((name) => name !== 'Marker').map((name) => ({
id: `component:${name}`,
label: prettyLabel(name),
category: 'Scripts',
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 2e429a969..51c8d0fa8 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 1300 stable · 17 beta · 0 deprecated
+Symbols: 1302 stable · 17 beta · 0 deprecated
## ABI_LAYOUT_HASH — const
```
@@ -3618,6 +3618,16 @@ static new (manifest: AddressableManifest): ManifestModel
static prototype: ManifestModel
```
+## Marker — const
+```
+ComponentDef<MarkerData>
+```
+
+## MarkerData — interface
+```
+type: string
+```
+
## MaskMode — type
```
(typeof MaskMode)[keyof typeof MaskMode]
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 4d0722e7a..a00403c30 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index.node
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 1299 stable · 19 beta · 0 deprecated
+Symbols: 1301 stable · 19 beta · 0 deprecated
## ANCHOR_AXES — const
```
@@ -3613,6 +3613,16 @@ static new (manifest: AddressableManifest): ManifestModel
static prototype: ManifestModel
```
+## Marker — const
+```
+ComponentDef<MarkerData>
+```
+
+## MarkerData — interface
+```
+type: string
+```
+
## MaskMode — type
```
(typeof MaskMode)[keyof typeof MaskMode]
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index aee4c9ae6..3a67668ef 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/wechat
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 1310 stable · 17 beta · 0 deprecated
+Symbols: 1312 stable · 17 beta · 0 deprecated
## ANCHOR_AXES — const
```
@@ -3620,6 +3620,16 @@ static new (manifest: AddressableManifest): ManifestModel
static prototype: ManifestModel
```
+## Marker — const
+```
+ComponentDef<MarkerData>
+```
+
+## MarkerData — interface
+```
+type: string
+```
+
## MaskMode — type
```
(typeof MaskMode)[keyof typeof MaskMode]
diff --git a/sdk/src/component.ts b/sdk/src/component.ts
index 8dd24dad9..28911423c 100644
--- a/sdk/src/component.ts
+++ b/sdk/src/component.ts
@@ -835,6 +835,22 @@ export const SceneOwner = defineComponent<SceneOwnerData>('SceneOwner', {
persistent: false,
});
+export interface MarkerData {
+ /** Gameplay identity — the game queries markers of a given kind (spawn point,
+ * waypoint, pickup, door, trigger …). Free-form: the game defines the vocabulary.
+ * `Query(Marker)` then filters by `type`. */
+ type: string;
+}
+
+/**
+ * A named point/region of gameplay interest, placed in the editor as a real entity.
+ * On its own (Transform + Marker) it's a spawn point / waypoint / location marker; add a
+ * sensor collider (the Trigger Area preset) and it's a trigger zone. Pure ECS — no
+ * 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 interface PostProcessVolumeData {
effects: {
type: string;
diff --git a/sdk/src/core-runtime.ts b/sdk/src/core-runtime.ts
index 4f6841d1f..2888174e1 100644
--- a/sdk/src/core-runtime.ts
+++ b/sdk/src/core-runtime.ts
@@ -104,6 +104,7 @@ export {
Disabled,
RuntimeOnly,
SceneOwner,
+ Marker,
ProjectionType,
ClearFlags,
ScaleMode,
@@ -128,6 +129,7 @@ export {
type CapsuleColliderData,
type NameData,
type SceneOwnerData,
+ type MarkerData,
ParticleEmitter,
EmitterShape,
SimulationSpace,
diff --git a/sdk/tests/marker-component.test.ts b/sdk/tests/marker-component.test.ts
new file mode 100644
index 000000000..adca74e6f
--- /dev/null
+++ b/sdk/tests/marker-component.test.ts
@@ -0,0 +1,61 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file The `Marker` gameplay component — a named point/region of interest placed as a
+ * real entity (spawn point / waypoint / trigger identity). It's a pure-TS
+ * `defineComponent`, so it must serialize into the scene, round-trip its `type`
+ * field, and be query-able like any component — the object-authoring foundation.
+ */
+import { describe, it, expect } from 'vitest';
+import { World } from '../src/world';
+import { Transform, Marker, markEngineComponentBaseline, seedEngineComponents } from '../src/component';
+import { serializeScene } from '../src/scene';
+import { createMockModule } from './mocks/wasm';
+
+// Snapshot the module-level engine components (incl. Marker) as the baseline — the SDK
+// entry does this at app start so they survive into every app context. A test World
+// activates its own context, so re-seed the baseline into it (else getComponentTypes'
+// registry match, which serializeScene relies on, can't resolve Marker's script id).
+markEngineComponentBaseline();
+
+function makeWorld(): World {
+ const mod = createMockModule();
+ const world = new World();
+ world.connectCpp(mod.getRegistry(), mod as never);
+ seedEngineComponents();
+ return world;
+}
+
+describe('Marker component', () => {
+ it('is a registered component with a string `type` default', () => {
+ expect(Marker._name).toBe('Marker');
+ expect(Marker._default).toEqual({ type: '' });
+ });
+
+ it('serializes into the scene and round-trips its `type`', () => {
+ 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' });
+
+ 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');
+ });
+
+ 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' });
+ const b = world.spawn('B');
+ world.insert(b, Marker, { type: 'pickup' });
+ world.spawn('C'); // no marker
+
+ const found = world.getEntitiesWithComponents([Marker]);
+ expect(found).toContain(a);
+ expect(found).toContain(b);
+ expect(found.length).toBe(2);
+ });
+});