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(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.mjsnew file mode 100644index 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.tsindex 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.tsindex 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 thediff --git a/desktop/templates/3d-starter/assets/scenes/main.esscene b/desktop/templates/3d-starter/assets/scenes/main.esscenenew file mode 100644index 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.metanew file mode 100644index 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.esprojectnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.jsonnew file mode 100644index 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"]+}