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): a 3D starter to begin a 3D game from, and an eye that opens on it

esengine5f03eefdc7c0
diff --git a/desktop/scripts/editor-checks/starter-3d.mjs b/desktop/scripts/editor-checks/starter-3d.mjs
new file mode 100644
index 000000000..b94722dd3
--- /dev/null
+++ b/desktop/scripts/editor-checks/starter-3d.mjs
@@ -0,0 +1,95 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file starter-3d — the 3D template a new project starts from actually runs.
+ *
+ * It is the first 3D thing a person sees: geometry, lights, a character, gravity
+ * and a key that moves it. Every one of those is a seam a document validator and a
+ * type-check pass straight over — they say the scene parses and the scripts
+ * compile, not that the world stands up.
+ *
+ * So this opens the template as a project, plays it, and asks the running game:
+ * does the character rest on the ground at the height its own mesh implies, and
+ * does the key the script reads move it there. The height is the claim that keeps
+ * the drawn shape and the solved shape the same size — a capsule sits radius plus
+ * half-height above what it stands on, and nothing but agreement puts it there.
+ */
+import path from 'node:path';
+import { checker, DESKTOP } from '../lib/editorDriver.mjs';
+
+const TEMPLATE = path.resolve(DESKTOP, 'templates', '3d-starter');
+
+export const name = 'starter-3d';
+export const describes = 'the 3D starter template stands up, and its key moves the character';
+
+/** `builtin:capsule` is built at radius 25 with a 25-unit cylinder half, so a
+ * uniform scale is the only thing between it and the shape a solver is given. */
+const CAPSULE_RADIUS = 25;
+const CAPSULE_HALF = 25;
+
+/** What the running game says about the one character in it. */
+const PROBE = 'const h = find("CharacterController3D")[0];'
+ + ' return { p: get(h.entity, "Transform").position, floor: h.data.isOnFloor,'
+ + ' r: h.data.radius, hh: h.data.halfHeight };';
+
+export async function run(ed) {
+ const check = checker();
+ await ed.open(TEMPLATE, 'assets/scenes/main.esscene');
+ await ed.call('run_editor_command', { id: 'mode.scene' }, 30000);
+ await ed.sleep(800);
+
+ await ed.call('set_play', { state: 'play' }, 180000);
+ await ed.sleep(2500);
+
+ const at = async () => ed.json('play_probe', { code: PROBE }, 60000);
+ const rest = await at();
+ if (!check(rest?.p != null, 'the running game has no character in it')) return check.failures;
+
+ check(rest.floor === true, 'the character is not on the floor — it fell through the ground or hangs above it');
+
+ // What the character is DRAWN as, from the document: the primitive's own size
+ // times the scale the template gives it.
+ const scale = await ed.json('get_field_value',
+ { entity: 8, component: 'Transform', key: 'scale' }, 30000);
+ if (!check(Array.isArray(scale) && scale[0] > 0, 'the character has no scale to read')) {
+ return check.failures;
+ }
+ const drawnRadius = CAPSULE_RADIUS * scale[0];
+ const drawnHalf = CAPSULE_HALF * scale[1];
+
+ // The shape drawn and the shape solved have to be one shape.
+ check(
+ Math.abs(rest.r - drawnRadius) < 0.5 && Math.abs(rest.hh - drawnHalf) < 0.5,
+ `the character is solved as radius ${rest.r} / half ${rest.hh} and drawn as ${drawnRadius} / `
+ + `${drawnHalf} — the capsule in the picture is not the capsule in the world`,
+ );
+
+ // And it rests exactly that far above the ground's surface at y = 0: a capsule
+ // stands on its lower cap.
+ const stand = drawnRadius + drawnHalf;
+ check(
+ Math.abs(rest.p.y - stand) < 1,
+ `the character rests at y = ${rest.p.y.toFixed(1)}, where the capsule it is drawn as puts it `
+ + `at ${stand} — it is sunk into the ground or hovering over it`,
+ );
+
+ // The key the template's own script reads, held over frames the game runs.
+ const before = rest.p.z;
+ await ed.call('play_input', { kind: 'key_down', code: 'KeyW' }, 30000);
+ await ed.json('play_probe', { code: 'await step(30, 1/60); return 1;' }, 60000);
+ const moved = await at();
+ await ed.call('play_input', { kind: 'key_up', code: 'KeyW' }, 30000);
+
+ check(
+ moved.p.z < before - 20,
+ `holding the walk key left the character at z = ${moved.p.z.toFixed(1)} from ${before.toFixed(1)} `
+ + '— the template ships a key that moves nothing',
+ );
+ check(
+ Math.abs(moved.p.y - stand) < 2,
+ `walking left the character at y = ${moved.p.y.toFixed(1)} rather than on the ground at ${stand}`,
+ );
+
+ await ed.call('set_play', { state: 'stop' }, 60000);
+ return check.failures;
+}
diff --git a/desktop/src/engine/EngineHost.ts b/desktop/src/engine/EngineHost.ts
index 6b5f21e52..9f48dffb4 100644
--- a/desktop/src/engine/EngineHost.ts
+++ b/desktop/src/engine/EngineHost.ts
@@ -9,6 +9,7 @@ import {
Transform,
Sprite,
Camera,
+ ProjectionType,
EditorView, editorViewHalfHeight, setEditorViewHalfHeight,
EditorGrid,
installEditorGrid,
@@ -329,6 +330,15 @@ class EngineHostImpl {
else view.active = false;
}
+ /**
+ * Whether the scene's active camera has a perspective, or null when the scene
+ * has no camera to ask. What the editor's own eye starts as — a scene whose
+ * camera sees depth is a scene with depth in it.
+ */
+ sceneUsesPerspective(): boolean | null {
+ return this.readSceneCamera()?.perspective ?? null;
+ }
+
/**
* Seed the editor camera from the scene's active camera and activate it for
* edit mode. Called after a scene loads; navigation thereafter is independent
@@ -423,7 +433,7 @@ class EngineHostImpl {
}
/** The active (or first) scene camera's center + ortho half-height, for seeding. */
- private readSceneCamera(): { x: number; y: number; orthoSize: number } | null {
+ private readSceneCamera(): { x: number; y: number; orthoSize: number; perspective: boolean } | null {
const world = this.world;
if (!world) return null;
let chosen: number | null = null;
@@ -437,8 +447,13 @@ class EngineHostImpl {
}
if (chosen == null) return null;
const t = world.get(chosen, Transform);
- const c = world.get(chosen, Camera) as { orthoSize?: number };
- return { x: t.position.x, y: t.position.y, orthoSize: c.orthoSize ?? 360 };
+ const c = world.get(chosen, Camera) as { orthoSize?: number; projectionType?: number };
+ return {
+ x: t.position.x,
+ y: t.position.y,
+ orthoSize: c.orthoSize ?? 360,
+ perspective: (c.projectionType ?? ProjectionType.Orthographic) === ProjectionType.Perspective,
+ };
}
// — Headless / automation drive —
diff --git a/desktop/src/project/ProjectStore.ts b/desktop/src/project/ProjectStore.ts
index a01d983d2..d80429d42 100644
--- a/desktop/src/project/ProjectStore.ts
+++ b/desktop/src/project/ProjectStore.ts
@@ -552,6 +552,11 @@ class ProjectStoreImpl {
for (const { id, tag } of tags) SceneModel.setPrefabTag(id, tag);
EngineHost.syncEditorViewToScene();
+ // The eye starts the way the scene's own camera looks — a scene whose camera has
+ // a perspective is a scene with depth. Through the toggle's own door, so the eye
+ // parks where 3D parks it. A first look, not a follow.
+ const perspective = EngineHost.sceneUsesPerspective();
+ if (perspective !== null) useEditorStore.setState({ viewPerspective: perspective });
// …and widen it to the design rect if the panel is narrower than the game's
// aspect. The sync above adopts the scene camera's orthoSize as a HALF-HEIGHT,
// which is the game's framing only while the panel is at least as wide as the
diff --git a/desktop/templates/3d-starter/assets/scenes/main.esscene b/desktop/templates/3d-starter/assets/scenes/main.esscene
new file mode 100644
index 000000000..b37eb7503
--- /dev/null
+++ b/desktop/templates/3d-starter/assets/scenes/main.esscene
@@ -0,0 +1,422 @@
+{
+ "version": 1,
+ "name": "Main",
+ "folders": [
+ "Lighting",
+ "World"
+ ],
+ "entities": [
+ {
+ "id": 0,
+ "name": "Camera",
+ "parent": null,
+ "children": [],
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 380,
+ "z": 900
+ },
+ "rotation": {
+ "x": -0.15643447,
+ "y": 0,
+ "z": 0,
+ "w": 0.98768834
+ }
+ }
+ },
+ {
+ "type": "Camera",
+ "data": {
+ "projectionType": 0,
+ "fov": 55,
+ "nearPlane": 10,
+ "farPlane": 5000,
+ "isActive": true,
+ "priority": 0,
+ "backgroundColor": {
+ "r": 0.09,
+ "g": 0.11,
+ "b": 0.15,
+ "a": 1
+ }
+ }
+ }
+ ],
+ "visible": true
+ },
+ {
+ "id": 1,
+ "name": "Sun",
+ "parent": null,
+ "children": [],
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 0,
+ "z": 0
+ },
+ "rotation": {
+ "w": 0.83394695,
+ "x": -0.52086316,
+ "y": 0.18230211,
+ "z": 0
+ }
+ }
+ },
+ {
+ "type": "Light2D",
+ "data": {
+ "type": 1,
+ "intensity": 1.05,
+ "enabled": true,
+ "color": {
+ "r": 1,
+ "g": 0.96,
+ "b": 0.9,
+ "a": 1
+ }
+ }
+ }
+ ],
+ "visible": true,
+ "folder": "Lighting"
+ },
+ {
+ "id": 2,
+ "name": "Sky",
+ "parent": null,
+ "children": [],
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 0,
+ "z": 0
+ }
+ }
+ },
+ {
+ "type": "Light2D",
+ "data": {
+ "type": 2,
+ "intensity": 0.42,
+ "enabled": true,
+ "color": {
+ "r": 0.55,
+ "g": 0.66,
+ "b": 0.85,
+ "a": 1
+ }
+ }
+ }
+ ],
+ "visible": true,
+ "folder": "Lighting"
+ },
+ {
+ "id": 3,
+ "name": "Ground",
+ "parent": null,
+ "children": [],
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 0,
+ "z": 0
+ },
+ "scale": {
+ "x": 10,
+ "y": 1,
+ "z": 7
+ }
+ }
+ },
+ {
+ "type": "Mesh2D",
+ "data": {
+ "mesh": "builtin:plane",
+ "lit": true,
+ "opaque": true,
+ "cullBackfaces": false,
+ "color": {
+ "r": 0.3,
+ "g": 0.36,
+ "b": 0.3,
+ "a": 1
+ }
+ }
+ }
+ ],
+ "visible": true,
+ "folder": "World"
+ },
+ {
+ "id": 4,
+ "name": "GroundBody",
+ "parent": null,
+ "children": [],
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": -40,
+ "z": 0
+ }
+ }
+ },
+ {
+ "type": "RigidBody3D",
+ "data": {
+ "bodyType": 0
+ }
+ },
+ {
+ "type": "BoxCollider3D",
+ "data": {
+ "halfExtents": {
+ "x": 500,
+ "y": 40,
+ "z": 350
+ },
+ "friction": 0.6
+ }
+ }
+ ],
+ "visible": true,
+ "folder": "World"
+ },
+ {
+ "id": 5,
+ "name": "Block",
+ "parent": null,
+ "children": [],
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": -230,
+ "y": 60,
+ "z": -80
+ },
+ "scale": {
+ "x": 1.2,
+ "y": 1.2,
+ "z": 1.2
+ }
+ }
+ },
+ {
+ "type": "Mesh2D",
+ "data": {
+ "mesh": "builtin:cube",
+ "lit": true,
+ "opaque": true,
+ "cullBackfaces": true,
+ "color": {
+ "r": 0.42,
+ "g": 0.34,
+ "b": 0.28,
+ "a": 1
+ }
+ }
+ },
+ {
+ "type": "RigidBody3D",
+ "data": {
+ "bodyType": 0
+ }
+ },
+ {
+ "type": "BoxCollider3D",
+ "data": {
+ "halfExtents": {
+ "x": 60,
+ "y": 60,
+ "z": 60
+ },
+ "friction": 0.6
+ }
+ }
+ ],
+ "visible": true,
+ "folder": "World"
+ },
+ {
+ "id": 6,
+ "name": "Pillar",
+ "parent": null,
+ "children": [],
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 210,
+ "y": 140,
+ "z": -170
+ },
+ "scale": {
+ "x": 0.8,
+ "y": 2.8,
+ "z": 0.8
+ }
+ }
+ },
+ {
+ "type": "Mesh2D",
+ "data": {
+ "mesh": "builtin:cube",
+ "lit": true,
+ "opaque": true,
+ "cullBackfaces": true,
+ "color": {
+ "r": 0.36,
+ "g": 0.38,
+ "b": 0.46,
+ "a": 1
+ }
+ }
+ },
+ {
+ "type": "RigidBody3D",
+ "data": {
+ "bodyType": 0
+ }
+ },
+ {
+ "type": "BoxCollider3D",
+ "data": {
+ "halfExtents": {
+ "x": 40,
+ "y": 140,
+ "z": 40
+ },
+ "friction": 0.6
+ }
+ }
+ ],
+ "visible": true,
+ "folder": "World"
+ },
+ {
+ "id": 7,
+ "name": "Step",
+ "parent": null,
+ "children": [],
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 170,
+ "y": 25,
+ "z": 130
+ },
+ "scale": {
+ "x": 3.0,
+ "y": 0.5,
+ "z": 1.6
+ }
+ }
+ },
+ {
+ "type": "Mesh2D",
+ "data": {
+ "mesh": "builtin:cube",
+ "lit": true,
+ "opaque": true,
+ "cullBackfaces": true,
+ "color": {
+ "r": 0.34,
+ "g": 0.3,
+ "b": 0.26,
+ "a": 1
+ }
+ }
+ },
+ {
+ "type": "RigidBody3D",
+ "data": {
+ "bodyType": 0
+ }
+ },
+ {
+ "type": "BoxCollider3D",
+ "data": {
+ "halfExtents": {
+ "x": 150,
+ "y": 25,
+ "z": 80
+ },
+ "friction": 0.6
+ }
+ }
+ ],
+ "visible": true,
+ "folder": "World"
+ },
+ {
+ "id": 8,
+ "name": "Hero",
+ "parent": null,
+ "children": [],
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 80,
+ "z": 170
+ },
+ "scale": {
+ "x": 1.6,
+ "y": 1.6,
+ "z": 1.6
+ }
+ }
+ },
+ {
+ "type": "Mesh2D",
+ "data": {
+ "mesh": "builtin:capsule",
+ "lit": true,
+ "opaque": true,
+ "cullBackfaces": true,
+ "color": {
+ "r": 0.85,
+ "g": 0.62,
+ "b": 0.3,
+ "a": 1
+ }
+ }
+ },
+ {
+ "type": "CharacterController3D",
+ "data": {
+ "radius": 40,
+ "halfHeight": 40,
+ "stepHeight": 45,
+ "snapDown": 50
+ }
+ }
+ ],
+ "visible": true
+ }
+ ]
+}
diff --git a/desktop/templates/3d-starter/assets/scenes/main.esscene.meta b/desktop/templates/3d-starter/assets/scenes/main.esscene.meta
new file mode 100644
index 000000000..64f13d173
--- /dev/null
+++ b/desktop/templates/3d-starter/assets/scenes/main.esscene.meta
@@ -0,0 +1,8 @@
+{
+ "uuid": "26acdfa0-63e1-4b56-a736-315e34c2e7e1",
+ "version": "2.0",
+ "type": "scene",
+ "importer": {
+ "autoMigrate": true
+ }
+}
diff --git a/desktop/templates/3d-starter/project.esproject b/desktop/templates/3d-starter/project.esproject
new file mode 100644
index 000000000..3f7699f1a
--- /dev/null
+++ b/desktop/templates/3d-starter/project.esproject
@@ -0,0 +1,13 @@
+{
+ "formatVersion": "1",
+ "name": "3D Starter",
+ "tag": "Starter",
+ "description": "A lit 3D world with ground, props and a character you walk around \u2014 start a 3D game from something that already runs.",
+ "version": "0.1.0",
+ "defaultScene": "assets/scenes/main.esscene",
+ "designResolution": {
+ "width": 960,
+ "height": 640
+ },
+ "spineVersion": "none"
+}
diff --git a/desktop/templates/3d-starter/src/main.ts b/desktop/templates/3d-starter/src/main.ts
new file mode 100644
index 000000000..61a1f1755
--- /dev/null
+++ b/desktop/templates/3d-starter/src/main.ts
@@ -0,0 +1,10 @@
+import { addSystemToSchedule, Schedule } from 'esengine';
+
+import { walkSystem } from './systems/walk';
+import { cameraFollowSystem } from './systems/camera';
+
+// A scene carrying 3D components brings the 3D world with it — nothing to register.
+// Walking is written in the fixed step, where the character solver reads it; the
+// camera follows in the render step, so it is smooth at the display's own rate.
+addSystemToSchedule(Schedule.FixedPreUpdate, walkSystem);
+addSystemToSchedule(Schedule.PostUpdate, cameraFollowSystem);
diff --git a/desktop/templates/3d-starter/src/systems/camera.ts b/desktop/templates/3d-starter/src/systems/camera.ts
new file mode 100644
index 000000000..576c985aa
--- /dev/null
+++ b/desktop/templates/3d-starter/src/systems/camera.ts
@@ -0,0 +1,30 @@
+import {
+ defineSystem, Query, Mut, Res, Time, Transform, Camera, CharacterController3D,
+} from 'esengine';
+
+/** Where the eye sits relative to the character: behind it and above it. */
+const OFFSET = { x: 0, y: 380, z: 900 };
+/** Fraction of the remaining distance closed per second — a lag the eye reads as
+ * weight rather than as the camera being late. */
+const CATCH_UP = 4;
+
+export const cameraFollowSystem = defineSystem(
+ [Query(Mut(Transform), Camera), Query(Transform, CharacterController3D), Res(Time)],
+ (cameras, characters, time) => {
+ let target: { x: number; y: number; z: number } | null = null;
+ for (const [, transform] of characters) {
+ target = transform.position;
+ break;
+ }
+ if (!target) return;
+
+ const t = Math.min(1, CATCH_UP * time.delta);
+ for (const [, transform] of cameras) {
+ const p = transform.position;
+ p.x += (target.x + OFFSET.x - p.x) * t;
+ p.y += (target.y + OFFSET.y - p.y) * t;
+ p.z += (target.z + OFFSET.z - p.z) * t;
+ }
+ },
+ { name: 'CameraFollowSystem' },
+);
diff --git a/desktop/templates/3d-starter/src/systems/walk.ts b/desktop/templates/3d-starter/src/systems/walk.ts
new file mode 100644
index 000000000..f32522dd3
--- /dev/null
+++ b/desktop/templates/3d-starter/src/systems/walk.ts
@@ -0,0 +1,33 @@
+import {
+ defineSystem, Query, Mut, Res, Input,
+ CharacterController3D,
+} from 'esengine';
+
+const WALK_SPEED = 340;
+const JUMP_SPEED = 560;
+
+/**
+ * Walk the character on the ground plane (x and z) and jump off it. Only the
+ * horizontal components are written each frame — the vertical one is the world's,
+ * so leaving it alone means "walk" rather than "hang in the air". The diagonal is
+ * normalised, or two keys would be ~1.4x faster than one.
+ */
+export const walkSystem = defineSystem(
+ [Query(Mut(CharacterController3D)), Res(Input)],
+ (characters, input) => {
+ let x = 0;
+ let z = 0;
+ if (input.isKeyDown('KeyA') || input.isKeyDown('ArrowLeft')) x -= 1;
+ if (input.isKeyDown('KeyD') || input.isKeyDown('ArrowRight')) x += 1;
+ if (input.isKeyDown('KeyW') || input.isKeyDown('ArrowUp')) z -= 1;
+ if (input.isKeyDown('KeyS') || input.isKeyDown('ArrowDown')) z += 1;
+ const length = Math.hypot(x, z);
+
+ for (const [, character] of characters) {
+ character.velocity.x = length > 0 ? (x / length) * WALK_SPEED : 0;
+ character.velocity.z = length > 0 ? (z / length) * WALK_SPEED : 0;
+ if (input.isKeyDown('Space') && character.isOnFloor) character.velocity.y = JUMP_SPEED;
+ }
+ },
+ { name: 'WalkSystem' },
+);
diff --git a/desktop/templates/3d-starter/tsconfig.json b/desktop/templates/3d-starter/tsconfig.json
new file mode 100644
index 000000000..1f11ff310
--- /dev/null
+++ b/desktop/templates/3d-starter/tsconfig.json
@@ -0,0 +1,20 @@
+{
+ "compilerOptions": {
+ "target": "ES2020",
+ "module": "ESNext",
+ "moduleResolution": "bundler",
+ "strict": true,
+ "esModuleInterop": true,
+ "skipLibCheck": true,
+ "forceConsistentCasingInFileNames": true,
+ "declaration": false,
+ "outDir": "./dist",
+ "rootDir": ".",
+ "paths": {
+ "esengine": ["./.esengine/sdk/index.d.ts"],
+ "esengine/wasm": ["./.esengine/sdk/wasm.d.ts"]
+ }
+ },
+ "include": ["src/**/*"],
+ "exclude": ["node_modules"]
+}