BlueGit

timfa questward

Allow any sprite size with a bottom pivot, Y-sort, and red closed-chunk borders.

Co-authored-by: Cursor <cursoragent@cursor.com>

timfa Tim Falken · pushed by timfa

Authored 2026-08-24 · 2 months ago

Hash
a54d0510103093e2cb3a74e58dca2a23ad64d066
Parent
9a190375
15 files changed +316 −100
README.md +1 −1
@@ -7,7 +7,7 @@ Authoritative Node.js tile MMO with a FrameworkV3 web client. Architecture lives
7 7 - `shared/` — protocol constants and tile definitions used by server and client
8 8 - `server/src/` — Node.js simulation, persistence, editor API, gateway
9 9 - `client/src/` — game client on top of FrameworkV3
10 - `client/assets/` — 16×16 world sprites
10 - `client/assets/` — world sprites (any size; pivot is 8px from the bottom)
11 11 - `client/frameworkv3/` — FrameworkV3 git submodule
12 12
13 13 ## Run locally
@@ -7,7 +7,7 @@ Authoritative Node.js tile MMO with a FrameworkV3 web client. Architecture lives
7- `shared/` — protocol constants and tile definitions used by server and client
7- `shared/` — protocol constants and tile definitions used by server and client
8- `server/src/` — Node.js simulation, persistence, editor API, gateway
8- `server/src/` — Node.js simulation, persistence, editor API, gateway
9- `client/src/` — game client on top of FrameworkV3
9- `client/src/` — game client on top of FrameworkV3
10- `client/assets/` — 16×16 world sprites
10- `client/assets/` — world sprites (any size; pivot is 8px from the bottom)
11- `client/frameworkv3/` — FrameworkV3 git submodule
11- `client/frameworkv3/` — FrameworkV3 git submodule
12
12
13## Run locally
13## Run locally
client/src/editor/main.js +9 −3
@@ -1,7 +1,7 @@
1 1 import { MessageType, CHUNK_SIZE, SPRITE_SIZE_PX, VISIBLE_CHUNK_RADIUS } from "/shared/protocol/constants.js";
2 2 import { GROUND_DEFINITIONS, BLOCK_DEFINITIONS, GroundType } from "/shared/definitions/tiles.js";
3 3 import { GameSocket, defaultSocketUrl } from "../net/socket.js";
4 import { PLAY_IMAGES, assertSpriteSizes, useNearestNeighbour } from "../render/sprites.js";
4 import { PLAY_IMAGES, useNearestNeighbour } from "../render/sprites.js";
5 5 import { WorldView } from "../render/worldView.js";
6 6
7 7 const game = new Game();
@@ -48,6 +48,8 @@ function snapshotFromPayload (payload)
48 48 return {
49 49 chunkX: payload.chunkX,
50 50 chunkY: payload.chunkY,
51 open: payload.data.open,
52 closedEdges: payload.closedEdges,
51 53 grounds: payload.data.grounds,
52 54 blocks: payload.data.blocks,
53 55 light: payload.data.light,
@@ -69,6 +71,8 @@ function paintAt (localX, localY)
69 71 view.applySnapshot({
70 72 chunkX,
71 73 chunkY,
74 open: draft.open,
75 closedEdges: view.chunks.get(`${chunkX},${chunkY}`)?.closedEdges,
72 76 grounds: draft.grounds,
73 77 blocks: draft.blocks,
74 78 light: draft.light,
@@ -194,7 +198,6 @@ function requestNeighbors ()
194 198 async function main ()
195 199 {
196 200 await game.preloadImages(PLAY_IMAGES);
197 assertSpriteSizes(game.images);
198 201 scene = new Scene(250, 56, 64, 64);
199 202 game.loadScene(scene);
200 203 useNearestNeighbour(scene, game.images);
@@ -268,7 +271,10 @@ $("east").addEventListener("click", () => loadNeighborhood(chunkX + 1, chunkY));
268 271 $("open").addEventListener("change", () =>
269 272 {
270 273 if (draft)
271 { draft.open = $("open").checked; }
274 {
275 draft.open = $("open").checked;
276 view.setChunkOpen(chunkX, chunkY, draft.open);
277 }
272 278 });
273 279 $("save").addEventListener("click", () =>
274 280 {
@@ -1,7 +1,7 @@
1import { MessageType, CHUNK_SIZE, SPRITE_SIZE_PX, VISIBLE_CHUNK_RADIUS } from "/shared/protocol/constants.js";
1import { MessageType, CHUNK_SIZE, SPRITE_SIZE_PX, VISIBLE_CHUNK_RADIUS } from "/shared/protocol/constants.js";
2import { GROUND_DEFINITIONS, BLOCK_DEFINITIONS, GroundType } from "/shared/definitions/tiles.js";
2import { GROUND_DEFINITIONS, BLOCK_DEFINITIONS, GroundType } from "/shared/definitions/tiles.js";
3import { GameSocket, defaultSocketUrl } from "../net/socket.js";
3import { GameSocket, defaultSocketUrl } from "../net/socket.js";
4import { PLAY_IMAGES, assertSpriteSizes, useNearestNeighbour } from "../render/sprites.js";
4import { PLAY_IMAGES, useNearestNeighbour } from "../render/sprites.js";
5import { WorldView } from "../render/worldView.js";
5import { WorldView } from "../render/worldView.js";
6
6
7const game = new Game();
7const game = new Game();
@@ -48,6 +48,8 @@ function snapshotFromPayload (payload)
48 return {
48 return {
49 chunkX: payload.chunkX,
49 chunkX: payload.chunkX,
50 chunkY: payload.chunkY,
50 chunkY: payload.chunkY,
51 open: payload.data.open,
52 closedEdges: payload.closedEdges,
51 grounds: payload.data.grounds,
53 grounds: payload.data.grounds,
52 blocks: payload.data.blocks,
54 blocks: payload.data.blocks,
53 light: payload.data.light,
55 light: payload.data.light,
@@ -69,6 +71,8 @@ function paintAt (localX, localY)
69 view.applySnapshot({
71 view.applySnapshot({
70 chunkX,
72 chunkX,
71 chunkY,
73 chunkY,
74 open: draft.open,
75 closedEdges: view.chunks.get(`${chunkX},${chunkY}`)?.closedEdges,
72 grounds: draft.grounds,
76 grounds: draft.grounds,
73 blocks: draft.blocks,
77 blocks: draft.blocks,
74 light: draft.light,
78 light: draft.light,
@@ -194,7 +198,6 @@ function requestNeighbors ()
194async function main ()
198async function main ()
195{
199{
196 await game.preloadImages(PLAY_IMAGES);
200 await game.preloadImages(PLAY_IMAGES);
197 assertSpriteSizes(game.images);
198 scene = new Scene(250, 56, 64, 64);
201 scene = new Scene(250, 56, 64, 64);
199 game.loadScene(scene);
202 game.loadScene(scene);
200 useNearestNeighbour(scene, game.images);
203 useNearestNeighbour(scene, game.images);
@@ -268,7 +271,10 @@ $("east").addEventListener("click", () => loadNeighborhood(chunkX + 1, chunkY));
268$("open").addEventListener("change", () =>
271$("open").addEventListener("change", () =>
269{
272{
270 if (draft)
273 if (draft)
271 { draft.open = $("open").checked; }
274 {
275 draft.open = $("open").checked;
276 view.setChunkOpen(chunkX, chunkY, draft.open);
277 }
272});
278});
273$("save").addEventListener("click", () =>
279$("save").addEventListener("click", () =>
274{
280{
client/src/play/main.js +1 −2
@@ -1,6 +1,6 @@
1 1 import { MessageType, GAIT } from "/shared/protocol/constants.js";
2 2 import { GameSocket, defaultSocketUrl } from "../net/socket.js";
3 import { PLAY_IMAGES, assertSpriteSizes, useNearestNeighbour } from "../render/sprites.js";
3 import { PLAY_IMAGES, useNearestNeighbour } from "../render/sprites.js";
4 4 import { WorldView } from "../render/worldView.js";
5 5
6 6 const game = new Game();
@@ -104,7 +104,6 @@ function startPlay (payload)
104 104 async function main ()
105 105 {
106 106 await game.preloadImages(PLAY_IMAGES);
107 assertSpriteSizes(game.images);
108 107 game.startGame();
109 108
110 109 socket = new GameSocket(defaultSocketUrl(), (message) =>
@@ -1,6 +1,6 @@
1import { MessageType, GAIT } from "/shared/protocol/constants.js";
1import { MessageType, GAIT } from "/shared/protocol/constants.js";
2import { GameSocket, defaultSocketUrl } from "../net/socket.js";
2import { GameSocket, defaultSocketUrl } from "../net/socket.js";
3import { PLAY_IMAGES, assertSpriteSizes, useNearestNeighbour } from "../render/sprites.js";
3import { PLAY_IMAGES, useNearestNeighbour } from "../render/sprites.js";
4import { WorldView } from "../render/worldView.js";
4import { WorldView } from "../render/worldView.js";
5
5
6const game = new Game();
6const game = new Game();
@@ -104,7 +104,6 @@ function startPlay (payload)
104async function main ()
104async function main ()
105{
105{
106 await game.preloadImages(PLAY_IMAGES);
106 await game.preloadImages(PLAY_IMAGES);
107 assertSpriteSizes(game.images);
108 game.startGame();
107 game.startGame();
109
108
110 socket = new GameSocket(defaultSocketUrl(), (message) =>
109 socket = new GameSocket(defaultSocketUrl(), (message) =>
client/src/render/sprites.js +4 −17
@@ -7,34 +7,21 @@ export const PLAY_IMAGES = [
7 7 { name: "block-torch", url: "/assets/blocks/block-torch.png" },
8 8 { name: "player-body-male", url: "/assets/characters/player-body-male.png" },
9 9 { name: "player-body-female", url: "/assets/characters/player-body-female.png" },
10 { name: "night-shade", url: shadeDataUrl() }
10 { name: "night-shade", url: shadeDataUrl("#000000") },
11 { name: "chunk-edge", url: shadeDataUrl("#e23d3d") }
11 12 ];
12 13
13 export function shadeDataUrl ()
14 export function shadeDataUrl (fill = "#000000")
14 15 {
15 16 const canvas = document.createElement("canvas");
16 17 canvas.width = SPRITE_SIZE_PX;
17 18 canvas.height = SPRITE_SIZE_PX;
18 19 const context = canvas.getContext("2d");
19 context.fillStyle = "#000000";
20 context.fillStyle = fill;
20 21 context.fillRect(0, 0, SPRITE_SIZE_PX, SPRITE_SIZE_PX);
21 22 return canvas.toDataURL("image/png");
22 23 }
23 24
24 export function assertSpriteSizes (images)
25 {
26 const offenders = [];
27 for (const [name, sprite] of Object.entries(images))
28 {
29 if (sprite.width !== SPRITE_SIZE_PX || sprite.height !== SPRITE_SIZE_PX)
30 {
31 offenders.push(`${name} is ${sprite.width}×${sprite.height}`);
32 }
33 }
34 if (offenders.length)
35 { throw new Error(`World sprites must be ${SPRITE_SIZE_PX}×${SPRITE_SIZE_PX}. Offenders: ${offenders.join("; ")}`); }
36 }
37
38 25 export function useNearestNeighbour (scene, images)
39 26 {
40 27 const gl = scene.glContext.gl;
@@ -7,34 +7,21 @@ export const PLAY_IMAGES = [
7 { name: "block-torch", url: "/assets/blocks/block-torch.png" },
7 { name: "block-torch", url: "/assets/blocks/block-torch.png" },
8 { name: "player-body-male", url: "/assets/characters/player-body-male.png" },
8 { name: "player-body-male", url: "/assets/characters/player-body-male.png" },
9 { name: "player-body-female", url: "/assets/characters/player-body-female.png" },
9 { name: "player-body-female", url: "/assets/characters/player-body-female.png" },
10 { name: "night-shade", url: shadeDataUrl() }
10 { name: "night-shade", url: shadeDataUrl("#000000") },
11 { name: "chunk-edge", url: shadeDataUrl("#e23d3d") }
11];
12];
12
13
13export function shadeDataUrl ()
14export function shadeDataUrl (fill = "#000000")
14{
15{
15 const canvas = document.createElement("canvas");
16 const canvas = document.createElement("canvas");
16 canvas.width = SPRITE_SIZE_PX;
17 canvas.width = SPRITE_SIZE_PX;
17 canvas.height = SPRITE_SIZE_PX;
18 canvas.height = SPRITE_SIZE_PX;
18 const context = canvas.getContext("2d");
19 const context = canvas.getContext("2d");
19 context.fillStyle = "#000000";
20 context.fillStyle = fill;
20 context.fillRect(0, 0, SPRITE_SIZE_PX, SPRITE_SIZE_PX);
21 context.fillRect(0, 0, SPRITE_SIZE_PX, SPRITE_SIZE_PX);
21 return canvas.toDataURL("image/png");
22 return canvas.toDataURL("image/png");
22}
23}
23
24
24export function assertSpriteSizes (images)
25{
26 const offenders = [];
27 for (const [name, sprite] of Object.entries(images))
28 {
29 if (sprite.width !== SPRITE_SIZE_PX || sprite.height !== SPRITE_SIZE_PX)
30 {
31 offenders.push(`${name} is ${sprite.width}×${sprite.height}`);
32 }
33 }
34 if (offenders.length)
35 { throw new Error(`World sprites must be ${SPRITE_SIZE_PX}×${SPRITE_SIZE_PX}. Offenders: ${offenders.join("; ")}`); }
36}
37
38export function useNearestNeighbour (scene, images)
25export function useNearestNeighbour (scene, images)
39{
26{
40 const gl = scene.glContext.gl;
27 const gl = scene.glContext.gl;
client/src/render/worldView.js +171 −36
@@ -1,5 +1,12 @@
1 1 import { CHUNK_SIZE, SPRITE_SIZE_PX, GAIT } from "/shared/protocol/constants.js";
2 2 import { GROUND_DEFINITIONS, BLOCK_DEFINITIONS } from "/shared/definitions/tiles.js";
3 import { spriteCenterFromPivot, spriteDrawSize, tilePivot, ySortLayer } from "/shared/render/pivot.js";
4
5 const LAYER_GROUND = 0;
6 const LAYER_SHADE = 500000;
7 const LAYER_EDGE = 900000;
8 const SORT_BLOCK = 1;
9 const SORT_ENTITY = 2;
3 10
4 11 export class WorldView
5 12 {
@@ -11,6 +18,7 @@ export class WorldView
11 18 this.chunks = new Map();
12 19 this.tiles = new Map();
13 20 this.entities = new Map();
21 this.edges = new Map();
14 22 this.localEntityId = null;
15 23 this.settings = { walkTilesPerSecond: 2 };
16 24 this.worldHour = 12;
@@ -37,14 +45,16 @@ export class WorldView
37 45 const key = `${snapshot.chunkX},${snapshot.chunkY}`;
38 46 this.chunks.set(key, snapshot);
39 47 this.#rebuildChunk(snapshot);
40 for (const entity of snapshot.entities)
48 for (const entity of snapshot.entities ?? [])
41 49 { this.#upsertEntity(entity); }
50 this.#rebuildAllEdges();
42 51 }
43 52
44 53 removeChunk (chunkX, chunkY)
45 54 {
46 55 const key = `${chunkX},${chunkY}`;
47 56 this.chunks.delete(key);
57 this.#destroyEdges(key);
48 58 for (const [tileKey, objects] of [...this.tiles.entries()])
49 59 {
50 60 if (objects.chunkX === chunkX && objects.chunkY === chunkY)
@@ -55,6 +65,16 @@ export class WorldView
55 65 this.tiles.delete(tileKey);
56 66 }
57 67 }
68 this.#rebuildAllEdges();
69 }
70
71 setChunkOpen (chunkX, chunkY, open)
72 {
73 const snapshot = this.chunks.get(`${chunkX},${chunkY}`);
74 if (!snapshot)
75 { return; }
76 snapshot.open = !!open;
77 this.#rebuildAllEdges();
58 78 }
59 79
60 80 moveEntity (payload)
@@ -99,14 +119,14 @@ export class WorldView
99 119 const size = this.tileSize();
100 120 for (const entity of this.entities.values())
101 121 {
102 entity.visualX = entity.tileX * size + size / 2;
103 entity.visualY = entity.tileY * size + size / 2;
122 entity.visualX = tilePivot(entity.tileX, entity.tileY, size).x;
123 entity.visualY = tilePivot(entity.tileX, entity.tileY, size).y;
104 124 entity.fromX = entity.visualX;
105 125 entity.fromY = entity.visualY;
106 126 entity.lerpStarted = null;
107 if (entity.object)
108 { entity.object.transform.size = new vector(size, size); }
127 this.#placeEntity(entity);
109 128 }
129 this.#rebuildAllEdges();
110 130 }
111 131
112 132 tileSize ()
@@ -131,27 +151,21 @@ export class WorldView
131 151 const size = this.tileSize();
132 152 for (const entity of this.entities.values())
133 153 {
134 const targetX = entity.tileX * size + size / 2;
135 const targetY = entity.tileY * size + size / 2;
154 const target = tilePivot(entity.tileX, entity.tileY, size);
136 155 if (entity.lerpStarted != null)
137 156 {
138 157 const t = Math.min(1, (now - entity.lerpStarted) / entity.lerpMs);
139 entity.visualX = entity.fromX + (targetX - entity.fromX) * t;
140 entity.visualY = entity.fromY + (targetY - entity.fromY) * t;
158 entity.visualX = entity.fromX + (target.x - entity.fromX) * t;
159 entity.visualY = entity.fromY + (target.y - entity.fromY) * t;
141 160 if (t >= 1)
142 161 { entity.lerpStarted = null; }
143 162 }
144 163 else
145 164 {
146 entity.visualX = targetX;
147 entity.visualY = targetY;
148 }
149 if (entity.object)
150 {
151 entity.object.transform.position.x = entity.visualX;
152 entity.object.transform.position.y = entity.visualY;
153 entity.object.transform.size = new vector(size, size);
165 entity.visualX = target.x;
166 entity.visualY = target.y;
154 167 }
168 this.#placeEntity(entity);
155 169 }
156 170
157 171 this.#centerCamera();
@@ -179,26 +193,30 @@ export class WorldView
179 193 #upsertEntity (payload)
180 194 {
181 195 const size = this.tileSize();
196 const pivot = tilePivot(payload.tileX, payload.tileY, size);
182 197 let entity = this.entities.get(payload.entityId);
183 198 if (!entity)
184 199 {
185 200 const spriteName = payload.sex === "female" ? "player-body-female" : "player-body-male";
186 const object = new GameObject(0, 0, this.game.images[spriteName], 2);
201 const object = new GameObject(0, 0, this.game.images[spriteName], SORT_ENTITY);
187 202 this.scene.addObject(object);
188 entity = { object, visualX: 0, visualY: 0 };
203 entity = { object, visualX: pivot.x, visualY: pivot.y };
189 204 this.entities.set(payload.entityId, entity);
190 205 }
191 206 entity.tileX = payload.tileX;
192 207 entity.tileY = payload.tileY;
193 208 entity.gait = payload.gait;
194 209 entity.sex = payload.sex;
195 entity.visualX = payload.tileX * size + size / 2;
196 entity.visualY = payload.tileY * size + size / 2;
197 entity.fromX = entity.visualX;
198 entity.fromY = entity.visualY;
199 entity.object.transform.position.x = entity.visualX;
200 entity.object.transform.position.y = entity.visualY;
201 entity.object.transform.size = new vector(size, size);
210 entity.visualX = pivot.x;
211 entity.visualY = pivot.y;
212 entity.fromX = pivot.x;
213 entity.fromY = pivot.y;
214 this.#placeEntity(entity);
215 }
216
217 #placeEntity (entity)
218 {
219 this.#placePivoted(entity.object, entity.visualX, entity.visualY, entity.visualY, SORT_ENTITY);
202 220 }
203 221
204 222 #rebuildChunk (snapshot)
@@ -218,41 +236,158 @@ export class WorldView
218 236 objects = { chunkX: snapshot.chunkX, chunkY: snapshot.chunkY };
219 237 this.tiles.set(key, objects);
220 238 }
221 const px = tileX * size + size / 2;
222 const py = tileY * size + size / 2;
239 const pivot = tilePivot(tileX, tileY, size);
223 240 const groundName = GROUND_DEFINITIONS[snapshot.grounds[index]]?.sprite ?? "ground-grass";
224 objects.ground = this.#sprite(objects.ground, groundName, px, py, 0, size);
241 objects.ground = this.#ensureSprite(objects.ground, groundName, LAYER_GROUND);
242 this.#placePivoted(objects.ground, pivot.x, pivot.y, pivot.y, 0);
243 objects.ground.layer = LAYER_GROUND;
225 244 const block = snapshot.blocks[index];
226 245 const blockName = block ? BLOCK_DEFINITIONS[block.typeId]?.sprite : null;
227 246 if (blockName)
228 { objects.block = this.#sprite(objects.block, blockName, px, py, 1, size); }
247 {
248 objects.block = this.#ensureSprite(objects.block, blockName, SORT_BLOCK);
249 this.#placePivoted(objects.block, pivot.x, pivot.y, pivot.y, SORT_BLOCK);
250 }
229 251 else if (objects.block)
230 252 {
231 253 objects.block.destroy();
232 254 objects.block = null;
233 255 }
234 256 objects.light = snapshot.light[index] ?? 0;
235 objects.shade = this.#sprite(objects.shade, "night-shade", px, py, 3, size);
257 objects.shade = this.#tileFill(objects.shade, "night-shade", pivot.x, pivot.y, LAYER_SHADE + tileY);
236 258 objects.shade.renderer.alpha = 0;
237 259 }
238 260 }
239 261 }
240 262
241 #sprite (existing, name, x, y, layer, size)
263 #tileFill (existing, name, x, y, layer)
264 {
265 existing = this.#ensureSprite(existing, name, layer);
266 const size = this.tileSize();
267 existing.transform.position.x = x;
268 existing.transform.position.y = y;
269 existing.transform.size = new vector(size, size);
270 existing.layer = layer;
271 this.#markSortDirty();
272 return existing;
273 }
274
275 #placePivoted (object, pivotX, pivotY, sortY, subOrder)
242 276 {
243 if (!existing || existing.renderer.sprite !== this.game.images[name])
277 const sprite = object.renderer.sprite;
278 const zoom = this.zoom;
279 const draw = spriteDrawSize(sprite.width, sprite.height, zoom);
280 const center = spriteCenterFromPivot(pivotX, pivotY, sprite.height, zoom);
281 object.transform.position.x = center.x;
282 object.transform.position.y = center.y;
283 object.transform.size = new vector(draw.w, draw.h);
284 object.layer = ySortLayer(sortY, subOrder);
285 this.#markSortDirty();
286 }
287
288 #ensureSprite (existing, name, layer)
289 {
290 const sprite = this.game.images[name];
291 if (!existing || existing.renderer.sprite !== sprite)
244 292 {
245 293 existing?.destroy();
246 existing = new GameObject(x, y, this.game.images[name], layer);
294 existing = new GameObject(0, 0, sprite, layer);
247 295 this.scene.addObject(existing);
248 296 }
297 return existing;
298 }
299
300 #neighborClosed (snapshot, dir, dx, dy)
301 {
302 const other = this.chunks.get(`${snapshot.chunkX + dx},${snapshot.chunkY + dy}`);
303 if (other)
304 { return !other.open; }
305 return !!snapshot.closedEdges?.[dir];
306 }
307
308 #rebuildAllEdges ()
309 {
310 const seen = new Set();
311 for (const snapshot of this.chunks.values())
312 {
313 const key = `${snapshot.chunkX},${snapshot.chunkY}`;
314 seen.add(key);
315 this.#rebuildChunkEdges(snapshot);
316 }
317 for (const key of [...this.edges.keys()])
318 {
319 if (!seen.has(key))
320 { this.#destroyEdges(key); }
321 }
322 }
323
324 #rebuildChunkEdges (snapshot)
325 {
326 const key = `${snapshot.chunkX},${snapshot.chunkY}`;
327 let bars = this.edges.get(key);
328 if (!bars)
329 {
330 bars = {};
331 this.edges.set(key, bars);
332 }
333
334 const size = this.tileSize();
335 const chunkPx = CHUNK_SIZE * size;
336 const left = snapshot.chunkX * CHUNK_SIZE * size;
337 const top = snapshot.chunkY * CHUNK_SIZE * size;
338 const centerX = left + chunkPx / 2;
339 const centerY = top + chunkPx / 2;
340 const thickness = Math.max(2, Math.round(2 * this.zoom));
341 const draw = snapshot.open === true;
342
343 bars.north = this.#edgeBar(bars.north, draw && this.#neighborClosed(snapshot, "north", 0, -1),
344 centerX, top, chunkPx, thickness, true);
345 bars.south = this.#edgeBar(bars.south, draw && this.#neighborClosed(snapshot, "south", 0, 1),
346 centerX, top + chunkPx, chunkPx, thickness, true);
347 bars.west = this.#edgeBar(bars.west, draw && this.#neighborClosed(snapshot, "west", -1, 0),
348 left, centerY, chunkPx, thickness, false);
349 bars.east = this.#edgeBar(bars.east, draw && this.#neighborClosed(snapshot, "east", 1, 0),
350 left + chunkPx, centerY, chunkPx, thickness, false);
351 }
352
353 #edgeBar (existing, visible, x, y, length, thickness, horizontal)
354 {
355 if (!visible)
356 {
357 if (existing)
358 { existing.renderer.visible = false; }
359 return existing;
360 }
361
362 existing = this.#ensureSprite(existing, "chunk-edge", LAYER_EDGE);
363 existing.renderer.visible = true;
249 364 existing.transform.position.x = x;
250 365 existing.transform.position.y = y;
251 existing.transform.size = new vector(size, size);
252 existing.layer = layer;
366 existing.transform.size = horizontal
367 ? new vector(length, thickness)
368 : new vector(thickness, length);
369 existing.layer = LAYER_EDGE;
370 this.#markSortDirty();
253 371 return existing;
254 372 }
255 373
374 #destroyEdges (key)
375 {
376 const bars = this.edges.get(key);
377 if (!bars)
378 { return; }
379 bars.north?.destroy();
380 bars.east?.destroy();
381 bars.south?.destroy();
382 bars.west?.destroy();
383 this.edges.delete(key);
384 }
385
386 #markSortDirty ()
387 {
388 this.scene._sortDirty = true;
389 }
390
256 391 #updateShade ()
257 392 {
258 393 const hour = this.nightPreview ?? this.worldHour;
@@ -1,5 +1,12 @@
1import { CHUNK_SIZE, SPRITE_SIZE_PX, GAIT } from "/shared/protocol/constants.js";
1import { CHUNK_SIZE, SPRITE_SIZE_PX, GAIT } from "/shared/protocol/constants.js";
2import { GROUND_DEFINITIONS, BLOCK_DEFINITIONS } from "/shared/definitions/tiles.js";
2import { GROUND_DEFINITIONS, BLOCK_DEFINITIONS } from "/shared/definitions/tiles.js";
3import { spriteCenterFromPivot, spriteDrawSize, tilePivot, ySortLayer } from "/shared/render/pivot.js";
4
5const LAYER_GROUND = 0;
6const LAYER_SHADE = 500000;
7const LAYER_EDGE = 900000;
8const SORT_BLOCK = 1;
9const SORT_ENTITY = 2;
3
10
4export class WorldView
11export class WorldView
5{
12{
@@ -11,6 +18,7 @@ export class WorldView
11 this.chunks = new Map();
18 this.chunks = new Map();
12 this.tiles = new Map();
19 this.tiles = new Map();
13 this.entities = new Map();
20 this.entities = new Map();
21 this.edges = new Map();
14 this.localEntityId = null;
22 this.localEntityId = null;
15 this.settings = { walkTilesPerSecond: 2 };
23 this.settings = { walkTilesPerSecond: 2 };
16 this.worldHour = 12;
24 this.worldHour = 12;
@@ -37,14 +45,16 @@ export class WorldView
37 const key = `${snapshot.chunkX},${snapshot.chunkY}`;
45 const key = `${snapshot.chunkX},${snapshot.chunkY}`;
38 this.chunks.set(key, snapshot);
46 this.chunks.set(key, snapshot);
39 this.#rebuildChunk(snapshot);
47 this.#rebuildChunk(snapshot);
40 for (const entity of snapshot.entities)
48 for (const entity of snapshot.entities ?? [])
41 { this.#upsertEntity(entity); }
49 { this.#upsertEntity(entity); }
50 this.#rebuildAllEdges();
42 }
51 }
43
52
44 removeChunk (chunkX, chunkY)
53 removeChunk (chunkX, chunkY)
45 {
54 {
46 const key = `${chunkX},${chunkY}`;
55 const key = `${chunkX},${chunkY}`;
47 this.chunks.delete(key);
56 this.chunks.delete(key);
57 this.#destroyEdges(key);
48 for (const [tileKey, objects] of [...this.tiles.entries()])
58 for (const [tileKey, objects] of [...this.tiles.entries()])
49 {
59 {
50 if (objects.chunkX === chunkX && objects.chunkY === chunkY)
60 if (objects.chunkX === chunkX && objects.chunkY === chunkY)
@@ -55,6 +65,16 @@ export class WorldView
55 this.tiles.delete(tileKey);
65 this.tiles.delete(tileKey);
56 }
66 }
57 }
67 }
68 this.#rebuildAllEdges();
69 }
70
71 setChunkOpen (chunkX, chunkY, open)
72 {
73 const snapshot = this.chunks.get(`${chunkX},${chunkY}`);
74 if (!snapshot)
75 { return; }
76 snapshot.open = !!open;
77 this.#rebuildAllEdges();
58 }
78 }
59
79
60 moveEntity (payload)
80 moveEntity (payload)
@@ -99,14 +119,14 @@ export class WorldView
99 const size = this.tileSize();
119 const size = this.tileSize();
100 for (const entity of this.entities.values())
120 for (const entity of this.entities.values())
101 {
121 {
102 entity.visualX = entity.tileX * size + size / 2;
122 entity.visualX = tilePivot(entity.tileX, entity.tileY, size).x;
103 entity.visualY = entity.tileY * size + size / 2;
123 entity.visualY = tilePivot(entity.tileX, entity.tileY, size).y;
104 entity.fromX = entity.visualX;
124 entity.fromX = entity.visualX;
105 entity.fromY = entity.visualY;
125 entity.fromY = entity.visualY;
106 entity.lerpStarted = null;
126 entity.lerpStarted = null;
107 if (entity.object)
127 this.#placeEntity(entity);
108 { entity.object.transform.size = new vector(size, size); }
109 }
128 }
129 this.#rebuildAllEdges();
110 }
130 }
111
131
112 tileSize ()
132 tileSize ()
@@ -131,27 +151,21 @@ export class WorldView
131 const size = this.tileSize();
151 const size = this.tileSize();
132 for (const entity of this.entities.values())
152 for (const entity of this.entities.values())
133 {
153 {
134 const targetX = entity.tileX * size + size / 2;
154 const target = tilePivot(entity.tileX, entity.tileY, size);
135 const targetY = entity.tileY * size + size / 2;
136 if (entity.lerpStarted != null)
155 if (entity.lerpStarted != null)
137 {
156 {
138 const t = Math.min(1, (now - entity.lerpStarted) / entity.lerpMs);
157 const t = Math.min(1, (now - entity.lerpStarted) / entity.lerpMs);
139 entity.visualX = entity.fromX + (targetX - entity.fromX) * t;
158 entity.visualX = entity.fromX + (target.x - entity.fromX) * t;
140 entity.visualY = entity.fromY + (targetY - entity.fromY) * t;
159 entity.visualY = entity.fromY + (target.y - entity.fromY) * t;
141 if (t >= 1)
160 if (t >= 1)
142 { entity.lerpStarted = null; }
161 { entity.lerpStarted = null; }
143 }
162 }
144 else
163 else
145 {
164 {
146 entity.visualX = targetX;
165 entity.visualX = target.x;
147 entity.visualY = targetY;
166 entity.visualY = target.y;
148 }
149 if (entity.object)
150 {
151 entity.object.transform.position.x = entity.visualX;
152 entity.object.transform.position.y = entity.visualY;
153 entity.object.transform.size = new vector(size, size);
154 }
167 }
168 this.#placeEntity(entity);
155 }
169 }
156
170
157 this.#centerCamera();
171 this.#centerCamera();
@@ -179,26 +193,30 @@ export class WorldView
179 #upsertEntity (payload)
193 #upsertEntity (payload)
180 {
194 {
181 const size = this.tileSize();
195 const size = this.tileSize();
196 const pivot = tilePivot(payload.tileX, payload.tileY, size);
182 let entity = this.entities.get(payload.entityId);
197 let entity = this.entities.get(payload.entityId);
183 if (!entity)
198 if (!entity)
184 {
199 {
185 const spriteName = payload.sex === "female" ? "player-body-female" : "player-body-male";
200 const spriteName = payload.sex === "female" ? "player-body-female" : "player-body-male";
186 const object = new GameObject(0, 0, this.game.images[spriteName], 2);
201 const object = new GameObject(0, 0, this.game.images[spriteName], SORT_ENTITY);
187 this.scene.addObject(object);
202 this.scene.addObject(object);
188 entity = { object, visualX: 0, visualY: 0 };
203 entity = { object, visualX: pivot.x, visualY: pivot.y };
189 this.entities.set(payload.entityId, entity);
204 this.entities.set(payload.entityId, entity);
190 }
205 }
191 entity.tileX = payload.tileX;
206 entity.tileX = payload.tileX;
192 entity.tileY = payload.tileY;
207 entity.tileY = payload.tileY;
193 entity.gait = payload.gait;
208 entity.gait = payload.gait;
194 entity.sex = payload.sex;
209 entity.sex = payload.sex;
195 entity.visualX = payload.tileX * size + size / 2;
210 entity.visualX = pivot.x;
196 entity.visualY = payload.tileY * size + size / 2;
211 entity.visualY = pivot.y;
197 entity.fromX = entity.visualX;
212 entity.fromX = pivot.x;
198 entity.fromY = entity.visualY;
213 entity.fromY = pivot.y;
199 entity.object.transform.position.x = entity.visualX;
214 this.#placeEntity(entity);
200 entity.object.transform.position.y = entity.visualY;
215 }
201 entity.object.transform.size = new vector(size, size);
216
217 #placeEntity (entity)
218 {
219 this.#placePivoted(entity.object, entity.visualX, entity.visualY, entity.visualY, SORT_ENTITY);
202 }
220 }
203
221
204 #rebuildChunk (snapshot)
222 #rebuildChunk (snapshot)
@@ -218,41 +236,158 @@ export class WorldView
218 objects = { chunkX: snapshot.chunkX, chunkY: snapshot.chunkY };
236 objects = { chunkX: snapshot.chunkX, chunkY: snapshot.chunkY };
219 this.tiles.set(key, objects);
237 this.tiles.set(key, objects);
220 }
238 }
221 const px = tileX * size + size / 2;
239 const pivot = tilePivot(tileX, tileY, size);
222 const py = tileY * size + size / 2;
223 const groundName = GROUND_DEFINITIONS[snapshot.grounds[index]]?.sprite ?? "ground-grass";
240 const groundName = GROUND_DEFINITIONS[snapshot.grounds[index]]?.sprite ?? "ground-grass";
224 objects.ground = this.#sprite(objects.ground, groundName, px, py, 0, size);
241 objects.ground = this.#ensureSprite(objects.ground, groundName, LAYER_GROUND);
242 this.#placePivoted(objects.ground, pivot.x, pivot.y, pivot.y, 0);
243 objects.ground.layer = LAYER_GROUND;
225 const block = snapshot.blocks[index];
244 const block = snapshot.blocks[index];
226 const blockName = block ? BLOCK_DEFINITIONS[block.typeId]?.sprite : null;
245 const blockName = block ? BLOCK_DEFINITIONS[block.typeId]?.sprite : null;
227 if (blockName)
246 if (blockName)
228 { objects.block = this.#sprite(objects.block, blockName, px, py, 1, size); }
247 {
248 objects.block = this.#ensureSprite(objects.block, blockName, SORT_BLOCK);
249 this.#placePivoted(objects.block, pivot.x, pivot.y, pivot.y, SORT_BLOCK);
250 }
229 else if (objects.block)
251 else if (objects.block)
230 {
252 {
231 objects.block.destroy();
253 objects.block.destroy();
232 objects.block = null;
254 objects.block = null;
233 }
255 }
234 objects.light = snapshot.light[index] ?? 0;
256 objects.light = snapshot.light[index] ?? 0;
235 objects.shade = this.#sprite(objects.shade, "night-shade", px, py, 3, size);
257 objects.shade = this.#tileFill(objects.shade, "night-shade", pivot.x, pivot.y, LAYER_SHADE + tileY);
236 objects.shade.renderer.alpha = 0;
258 objects.shade.renderer.alpha = 0;
237 }
259 }
238 }
260 }
239 }
261 }
240
262
241 #sprite (existing, name, x, y, layer, size)
263 #tileFill (existing, name, x, y, layer)
264 {
265 existing = this.#ensureSprite(existing, name, layer);
266 const size = this.tileSize();
267 existing.transform.position.x = x;
268 existing.transform.position.y = y;
269 existing.transform.size = new vector(size, size);
270 existing.layer = layer;
271 this.#markSortDirty();
272 return existing;
273 }
274
275 #placePivoted (object, pivotX, pivotY, sortY, subOrder)
242 {
276 {
243 if (!existing || existing.renderer.sprite !== this.game.images[name])
277 const sprite = object.renderer.sprite;
278 const zoom = this.zoom;
279 const draw = spriteDrawSize(sprite.width, sprite.height, zoom);
280 const center = spriteCenterFromPivot(pivotX, pivotY, sprite.height, zoom);
281 object.transform.position.x = center.x;
282 object.transform.position.y = center.y;
283 object.transform.size = new vector(draw.w, draw.h);
284 object.layer = ySortLayer(sortY, subOrder);
285 this.#markSortDirty();
286 }
287
288 #ensureSprite (existing, name, layer)
289 {
290 const sprite = this.game.images[name];
291 if (!existing || existing.renderer.sprite !== sprite)
244 {
292 {
245 existing?.destroy();
293 existing?.destroy();
246 existing = new GameObject(x, y, this.game.images[name], layer);
294 existing = new GameObject(0, 0, sprite, layer);
247 this.scene.addObject(existing);
295 this.scene.addObject(existing);
248 }
296 }
297 return existing;
298 }
299
300 #neighborClosed (snapshot, dir, dx, dy)
301 {
302 const other = this.chunks.get(`${snapshot.chunkX + dx},${snapshot.chunkY + dy}`);
303 if (other)
304 { return !other.open; }
305 return !!snapshot.closedEdges?.[dir];
306 }
307
308 #rebuildAllEdges ()
309 {
310 const seen = new Set();
311 for (const snapshot of this.chunks.values())
312 {
313 const key = `${snapshot.chunkX},${snapshot.chunkY}`;
314 seen.add(key);
315 this.#rebuildChunkEdges(snapshot);
316 }
317 for (const key of [...this.edges.keys()])
318 {
319 if (!seen.has(key))
320 { this.#destroyEdges(key); }
321 }
322 }
323
324 #rebuildChunkEdges (snapshot)
325 {
326 const key = `${snapshot.chunkX},${snapshot.chunkY}`;
327 let bars = this.edges.get(key);
328 if (!bars)
329 {
330 bars = {};
331 this.edges.set(key, bars);
332 }
333
334 const size = this.tileSize();
335 const chunkPx = CHUNK_SIZE * size;
336 const left = snapshot.chunkX * CHUNK_SIZE * size;
337 const top = snapshot.chunkY * CHUNK_SIZE * size;
338 const centerX = left + chunkPx / 2;
339 const centerY = top + chunkPx / 2;
340 const thickness = Math.max(2, Math.round(2 * this.zoom));
341 const draw = snapshot.open === true;
342
343 bars.north = this.#edgeBar(bars.north, draw && this.#neighborClosed(snapshot, "north", 0, -1),
344 centerX, top, chunkPx, thickness, true);
345 bars.south = this.#edgeBar(bars.south, draw && this.#neighborClosed(snapshot, "south", 0, 1),
346 centerX, top + chunkPx, chunkPx, thickness, true);
347 bars.west = this.#edgeBar(bars.west, draw && this.#neighborClosed(snapshot, "west", -1, 0),
348 left, centerY, chunkPx, thickness, false);
349 bars.east = this.#edgeBar(bars.east, draw && this.#neighborClosed(snapshot, "east", 1, 0),
350 left + chunkPx, centerY, chunkPx, thickness, false);
351 }
352
353 #edgeBar (existing, visible, x, y, length, thickness, horizontal)
354 {
355 if (!visible)
356 {
357 if (existing)
358 { existing.renderer.visible = false; }
359 return existing;
360 }
361
362 existing = this.#ensureSprite(existing, "chunk-edge", LAYER_EDGE);
363 existing.renderer.visible = true;
249 existing.transform.position.x = x;
364 existing.transform.position.x = x;
250 existing.transform.position.y = y;
365 existing.transform.position.y = y;
251 existing.transform.size = new vector(size, size);
366 existing.transform.size = horizontal
252 existing.layer = layer;
367 ? new vector(length, thickness)
368 : new vector(thickness, length);
369 existing.layer = LAYER_EDGE;
370 this.#markSortDirty();
253 return existing;
371 return existing;
254 }
372 }
255
373
374 #destroyEdges (key)
375 {
376 const bars = this.edges.get(key);
377 if (!bars)
378 { return; }
379 bars.north?.destroy();
380 bars.east?.destroy();
381 bars.south?.destroy();
382 bars.west?.destroy();
383 this.edges.delete(key);
384 }
385
386 #markSortDirty ()
387 {
388 this.scene._sortDirty = true;
389 }
390
256 #updateShade ()
391 #updateShade ()
257 {
392 {
258 const hour = this.nightPreview ?? this.worldHour;
393 const hour = this.nightPreview ?? this.worldHour;
client/tests/sprite-size.test.js +2 −3
@@ -4,7 +4,6 @@ import { fileURLToPath } from "node:url";
4 4 import test from "node:test";
5 5 import assert from "node:assert/strict";
6 6
7 const SPRITE_SIZE = 16;
8 7 const ASSET_ROOT = join(fileURLToPath(new URL("..", import.meta.url)), "assets");
9 8 const SPRITE_FOLDERS = ["grounds", "blocks", "characters", "items", "equipment", "mobs"];
10 9
@@ -32,7 +31,7 @@ function listPngs (dir)
32 31 return files;
33 32 }
34 33
35 test("every world sprite is exactly 16×16", () =>
34 test("world sprite PNGs load with a positive size", () =>
36 35 {
37 36 const offenders = [];
38 37 for (const folder of SPRITE_FOLDERS)
@@ -50,7 +49,7 @@ test("every world sprite is exactly 16×16", () =>
50 49 for (const file of files)
51 50 {
52 51 const { width, height } = pngSize(readFileSync(file));
53 if (width !== SPRITE_SIZE || height !== SPRITE_SIZE)
52 if (width < 1 || height < 1)
54 53 { offenders.push(`${file} is ${width}×${height}`); }
55 54 }
56 55 }
@@ -4,7 +4,6 @@ import { fileURLToPath } from "node:url";
4import test from "node:test";
4import test from "node:test";
5import assert from "node:assert/strict";
5import assert from "node:assert/strict";
6
6
7const SPRITE_SIZE = 16;
8const ASSET_ROOT = join(fileURLToPath(new URL("..", import.meta.url)), "assets");
7const ASSET_ROOT = join(fileURLToPath(new URL("..", import.meta.url)), "assets");
9const SPRITE_FOLDERS = ["grounds", "blocks", "characters", "items", "equipment", "mobs"];
8const SPRITE_FOLDERS = ["grounds", "blocks", "characters", "items", "equipment", "mobs"];
10
9
@@ -32,7 +31,7 @@ function listPngs (dir)
32 return files;
31 return files;
33}
32}
34
33
35test("every world sprite is exactly 16×16", () =>
34test("world sprite PNGs load with a positive size", () =>
36{
35{
37 const offenders = [];
36 const offenders = [];
38 for (const folder of SPRITE_FOLDERS)
37 for (const folder of SPRITE_FOLDERS)
@@ -50,7 +49,7 @@ test("every world sprite is exactly 16×16", () =>
50 for (const file of files)
49 for (const file of files)
51 {
50 {
52 const { width, height } = pngSize(readFileSync(file));
51 const { width, height } = pngSize(readFileSync(file));
53 if (width !== SPRITE_SIZE || height !== SPRITE_SIZE)
52 if (width < 1 || height < 1)
54 { offenders.push(`${file} is ${width}×${height}`); }
53 { offenders.push(`${file} is ${width}×${height}`); }
55 }
54 }
56 }
55 }
docs/FEATURES.md +5 −5
@@ -22,8 +22,8 @@ Each entry is a short note on behaviour and where the code lives. Update this fi
22 22 ## Open and closed chunks
23 23
24 24 **Status:** full
25 **Spec:** Never-edited chunks are closed grass. Closed chunks can be replicated but cannot be entered; pathfinding treats them as impassable.
26 **Code:** `server/src/world/chunkData.js` (`open` flag), `server/src/simulation/simulation.js` (`isEnterable`, `#walkableFor`), editor save in `server/src/editor/service.js`
25 **Spec:** Never-edited chunks are closed grass. Closed chunks can be replicated but cannot be entered; pathfinding treats them as impassable. Open chunks draw a red border on edges that touch a closed neighbour.
26 **Code:** `server/src/world/chunkData.js` (`open` flag), `server/src/world/chunkFlags.js`, `server/src/simulation/simulation.js` (`isEnterable`, `#walkableFor`, `closedEdges`), `client/src/render/worldView.js` (`#rebuildChunkEdges`)
27 27
28 28 ## ECS registry and components
29 29
@@ -145,11 +145,11 @@ Each entry is a short note on behaviour and where the code lives. Update this fi
145 145 **Spec:** FrameworkV3 is a git submodule at `client/frameworkv3`, built first via `npm run build:client`. Game code lives in `client/src`. Server does not import it.
146 146 **Code:** `.gitmodules`, `client/frameworkv3`, `client/scripts/build-framework.mjs`
147 147
148 ## 16×16 sprite contract
148 ## Sprite size, pivot and Y-sort
149 149
150 150 **Status:** full
151 **Spec:** World sprites must be exactly 16×16. Reject at client load. The unit test walks `client/assets/{grounds,blocks,characters,...}` and fails listing every offender.
152 **Code:** `client/src/render/sprites.js` (`assertSpriteSizes`), `client/tests/sprite-size.test.js`, art in `client/assets/`
151 **Spec:** World sprites may be any pixel size. Pivot is horizontal centre and 8px from the sprite bottom, placed on the tile centre. Blocks and mobiles are Y-sorted (north behind south).
152 **Code:** `shared/render/pivot.js`, `client/src/render/worldView.js`, tests in `server/tests/pivot.test.js`
153 153
154 154 ## Region workers and cross-worker transfer
155 155
@@ -22,8 +22,8 @@ Each entry is a short note on behaviour and where the code lives. Update this fi
22## Open and closed chunks
22## Open and closed chunks
23
23
24**Status:** full
24**Status:** full
25**Spec:** Never-edited chunks are closed grass. Closed chunks can be replicated but cannot be entered; pathfinding treats them as impassable.
25**Spec:** Never-edited chunks are closed grass. Closed chunks can be replicated but cannot be entered; pathfinding treats them as impassable. Open chunks draw a red border on edges that touch a closed neighbour.
26**Code:** `server/src/world/chunkData.js` (`open` flag), `server/src/simulation/simulation.js` (`isEnterable`, `#walkableFor`), editor save in `server/src/editor/service.js`
26**Code:** `server/src/world/chunkData.js` (`open` flag), `server/src/world/chunkFlags.js`, `server/src/simulation/simulation.js` (`isEnterable`, `#walkableFor`, `closedEdges`), `client/src/render/worldView.js` (`#rebuildChunkEdges`)
27
27
28## ECS registry and components
28## ECS registry and components
29
29
@@ -145,11 +145,11 @@ Each entry is a short note on behaviour and where the code lives. Update this fi
145**Spec:** FrameworkV3 is a git submodule at `client/frameworkv3`, built first via `npm run build:client`. Game code lives in `client/src`. Server does not import it.
145**Spec:** FrameworkV3 is a git submodule at `client/frameworkv3`, built first via `npm run build:client`. Game code lives in `client/src`. Server does not import it.
146**Code:** `.gitmodules`, `client/frameworkv3`, `client/scripts/build-framework.mjs`
146**Code:** `.gitmodules`, `client/frameworkv3`, `client/scripts/build-framework.mjs`
147
147
148## 16×16 sprite contract
148## Sprite size, pivot and Y-sort
149
149
150**Status:** full
150**Status:** full
151**Spec:** World sprites must be exactly 16×16. Reject at client load. The unit test walks `client/assets/{grounds,blocks,characters,...}` and fails listing every offender.
151**Spec:** World sprites may be any pixel size. Pivot is horizontal centre and 8px from the sprite bottom, placed on the tile centre. Blocks and mobiles are Y-sorted (north behind south).
152**Code:** `client/src/render/sprites.js` (`assertSpriteSizes`), `client/tests/sprite-size.test.js`, art in `client/assets/`
152**Code:** `shared/render/pivot.js`, `client/src/render/worldView.js`, tests in `server/tests/pivot.test.js`
153
153
154## Region workers and cross-worker transfer
154## Region workers and cross-worker transfer
155
155
server/src/editor/service.js +9 −0
@@ -4,6 +4,7 @@ import { localToTile } from "../world/coordinates.js";
4 4 import { cloneChunkData, createEmptyChunkData, decodeChunkBlob, encodeChunkBlob } from "../world/chunkData.js";
5 5 import { BLOCK_DEFINITIONS } from "../../../shared/definitions/tiles.js";
6 6 import { bakeLightMaps, maxDefinitionLightRange } from "../lighting/baker.js";
7 import { closedNeighborEdges } from "../world/chunkFlags.js";
7 8
8 9 export class EditorService
9 10 {
@@ -20,6 +21,13 @@ export class EditorService
20 21 const data = row
21 22 ? decodeChunkBlob(row.data_blob, settings.defaultGroundTypeId)
22 23 : createEmptyChunkData(settings.defaultGroundTypeId);
24 const isOpen = (x, y) =>
25 {
26 const neighbor = this.worldDb.getChunkVersion(x, y, revisionId);
27 if (!neighbor)
28 { return false; }
29 return !!decodeChunkBlob(neighbor.data_blob, settings.defaultGroundTypeId).open;
30 };
23 31 return {
24 32 chunkX,
25 33 chunkY,
@@ -29,6 +37,7 @@ export class EditorService
29 37 authored: !!row,
30 38 settings,
31 39 data,
40 closedEdges: closedNeighborEdges(chunkX, chunkY, isOpen),
32 41 changelog: this.worldDb.listChangelog(chunkX, chunkY)
33 42 };
34 43 }
@@ -4,6 +4,7 @@ import { localToTile } from "../world/coordinates.js";
4import { cloneChunkData, createEmptyChunkData, decodeChunkBlob, encodeChunkBlob } from "../world/chunkData.js";
4import { cloneChunkData, createEmptyChunkData, decodeChunkBlob, encodeChunkBlob } from "../world/chunkData.js";
5import { BLOCK_DEFINITIONS } from "../../../shared/definitions/tiles.js";
5import { BLOCK_DEFINITIONS } from "../../../shared/definitions/tiles.js";
6import { bakeLightMaps, maxDefinitionLightRange } from "../lighting/baker.js";
6import { bakeLightMaps, maxDefinitionLightRange } from "../lighting/baker.js";
7import { closedNeighborEdges } from "../world/chunkFlags.js";
7
8
8export class EditorService
9export class EditorService
9{
10{
@@ -20,6 +21,13 @@ export class EditorService
20 const data = row
21 const data = row
21 ? decodeChunkBlob(row.data_blob, settings.defaultGroundTypeId)
22 ? decodeChunkBlob(row.data_blob, settings.defaultGroundTypeId)
22 : createEmptyChunkData(settings.defaultGroundTypeId);
23 : createEmptyChunkData(settings.defaultGroundTypeId);
24 const isOpen = (x, y) =>
25 {
26 const neighbor = this.worldDb.getChunkVersion(x, y, revisionId);
27 if (!neighbor)
28 { return false; }
29 return !!decodeChunkBlob(neighbor.data_blob, settings.defaultGroundTypeId).open;
30 };
23 return {
31 return {
24 chunkX,
32 chunkX,
25 chunkY,
33 chunkY,
@@ -29,6 +37,7 @@ export class EditorService
29 authored: !!row,
37 authored: !!row,
30 settings,
38 settings,
31 data,
39 data,
40 closedEdges: closedNeighborEdges(chunkX, chunkY, isOpen),
32 changelog: this.worldDb.listChangelog(chunkX, chunkY)
41 changelog: this.worldDb.listChangelog(chunkX, chunkY)
33 };
42 };
34 }
43 }
server/src/simulation/simulation.js +2 −0
@@ -3,6 +3,7 @@ import { tileToChunk, tileToLocal, chunkKey, visibleChunkCoords, tileKey } from
3 3 import { createEmptyChunkData, decodeChunkBlob, isChunkTilePassable } from "../world/chunkData.js";
4 4 import { EcsWorld } from "../ecs/world.js";
5 5 import { chunkBoundsAround, findPath } from "../navigation/astar.js";
6 import { closedNeighborEdges } from "../world/chunkFlags.js";
6 7
7 8 export class Simulation
8 9 {
@@ -349,6 +350,7 @@ export class Simulation
349 350 chunkX,
350 351 chunkY,
351 352 open: data.open,
353 closedEdges: closedNeighborEdges(chunkX, chunkY, (x, y) => this.#ensureChunk(x, y).open),
352 354 grounds: data.grounds,
353 355 blocks: data.blocks,
354 356 light: data.light,
@@ -3,6 +3,7 @@ import { tileToChunk, tileToLocal, chunkKey, visibleChunkCoords, tileKey } from
3import { createEmptyChunkData, decodeChunkBlob, isChunkTilePassable } from "../world/chunkData.js";
3import { createEmptyChunkData, decodeChunkBlob, isChunkTilePassable } from "../world/chunkData.js";
4import { EcsWorld } from "../ecs/world.js";
4import { EcsWorld } from "../ecs/world.js";
5import { chunkBoundsAround, findPath } from "../navigation/astar.js";
5import { chunkBoundsAround, findPath } from "../navigation/astar.js";
6import { closedNeighborEdges } from "../world/chunkFlags.js";
6
7
7export class Simulation
8export class Simulation
8{
9{
@@ -349,6 +350,7 @@ export class Simulation
349 chunkX,
350 chunkX,
350 chunkY,
351 chunkY,
351 open: data.open,
352 open: data.open,
353 closedEdges: closedNeighborEdges(chunkX, chunkY, (x, y) => this.#ensureChunk(x, y).open),
352 grounds: data.grounds,
354 grounds: data.grounds,
353 blocks: data.blocks,
355 blocks: data.blocks,
354 light: data.light,
356 light: data.light,
server/src/world/chunkFlags.js added +9 −0
@@ -0,0 +1,9 @@
1 export function closedNeighborEdges (chunkX, chunkY, isOpen)
2 {
3 return {
4 north: !isOpen(chunkX, chunkY - 1),
5 east: !isOpen(chunkX + 1, chunkY),
6 south: !isOpen(chunkX, chunkY + 1),
7 west: !isOpen(chunkX - 1, chunkY)
8 };
9 }
@@ -0,0 +1,9 @@
1export function closedNeighborEdges (chunkX, chunkY, isOpen)
2{
3 return {
4 north: !isOpen(chunkX, chunkY - 1),
5 east: !isOpen(chunkX + 1, chunkY),
6 south: !isOpen(chunkX, chunkY + 1),
7 west: !isOpen(chunkX - 1, chunkY)
8 };
9}
server/tests/chunk-flags.test.js added +13 −0
@@ -0,0 +1,13 @@
1 import test from "node:test";
2 import assert from "node:assert/strict";
3 import { closedNeighborEdges } from "../src/world/chunkFlags.js";
4
5 test("closed edges flag neighbours that are not enterable", () =>
6 {
7 const open = new Set(["0,0", "1,0"]);
8 const edges = closedNeighborEdges(0, 0, (x, y) => open.has(`${x},${y}`));
9 assert.equal(edges.east, false);
10 assert.equal(edges.west, true);
11 assert.equal(edges.north, true);
12 assert.equal(edges.south, true);
13 });
@@ -0,0 +1,13 @@
1import test from "node:test";
2import assert from "node:assert/strict";
3import { closedNeighborEdges } from "../src/world/chunkFlags.js";
4
5test("closed edges flag neighbours that are not enterable", () =>
6{
7 const open = new Set(["0,0", "1,0"]);
8 const edges = closedNeighborEdges(0, 0, (x, y) => open.has(`${x},${y}`));
9 assert.equal(edges.east, false);
10 assert.equal(edges.west, true);
11 assert.equal(edges.north, true);
12 assert.equal(edges.south, true);
13});
server/tests/pivot.test.js added +26 −0
@@ -0,0 +1,26 @@
1 import test from "node:test";
2 import assert from "node:assert/strict";
3 import { spriteCenterFromPivot, tilePivot, ySortLayer } from "../../shared/render/pivot.js";
4
5 test("a 16×16 sprite pivot sits on the tile centre", () =>
6 {
7 const pivot = tilePivot(0, 0, 16);
8 const center = spriteCenterFromPivot(pivot.x, pivot.y, 16, 1);
9 assert.equal(pivot.x, 8);
10 assert.equal(pivot.y, 8);
11 assert.equal(center.x, 8);
12 assert.equal(center.y, 8);
13 });
14
15 test("a taller sprite keeps its feet 8px from the bottom on the tile centre", () =>
16 {
17 const pivot = tilePivot(0, 0, 16);
18 const center = spriteCenterFromPivot(pivot.x, pivot.y, 32, 1);
19 assert.equal(center.x, 8);
20 assert.equal(center.y, 0);
21 });
22
23 test("Y-sort puts a southern tile in front of a northern tile", () =>
24 {
25 assert.ok(ySortLayer(16, 1) > ySortLayer(0, 1));
26 });
@@ -0,0 +1,26 @@
1import test from "node:test";
2import assert from "node:assert/strict";
3import { spriteCenterFromPivot, tilePivot, ySortLayer } from "../../shared/render/pivot.js";
4
5test("a 16×16 sprite pivot sits on the tile centre", () =>
6{
7 const pivot = tilePivot(0, 0, 16);
8 const center = spriteCenterFromPivot(pivot.x, pivot.y, 16, 1);
9 assert.equal(pivot.x, 8);
10 assert.equal(pivot.y, 8);
11 assert.equal(center.x, 8);
12 assert.equal(center.y, 8);
13});
14
15test("a taller sprite keeps its feet 8px from the bottom on the tile centre", () =>
16{
17 const pivot = tilePivot(0, 0, 16);
18 const center = spriteCenterFromPivot(pivot.x, pivot.y, 32, 1);
19 assert.equal(center.x, 8);
20 assert.equal(center.y, 0);
21});
22
23test("Y-sort puts a southern tile in front of a northern tile", () =>
24{
25 assert.ok(ySortLayer(16, 1) > ySortLayer(0, 1));
26});
shared/protocol/constants.js +1 −0
@@ -1,6 +1,7 @@
1 1 export const CHUNK_SIZE = 16;
2 2 export const REGION_CHUNKS = 4;
3 3 export const SPRITE_SIZE_PX = 16;
4 export const PIVOT_FROM_BOTTOM_PX = 8;
4 5 export const VISIBLE_CHUNK_RADIUS = 1;
5 6
6 7 export const WORLD_YEAR_OFFSET = 1200;
@@ -1,6 +1,7 @@
1export const CHUNK_SIZE = 16;
1export const CHUNK_SIZE = 16;
2export const REGION_CHUNKS = 4;
2export const REGION_CHUNKS = 4;
3export const SPRITE_SIZE_PX = 16;
3export const SPRITE_SIZE_PX = 16;
4export const PIVOT_FROM_BOTTOM_PX = 8;
4export const VISIBLE_CHUNK_RADIUS = 1;
5export const VISIBLE_CHUNK_RADIUS = 1;
5
6
6export const WORLD_YEAR_OFFSET = 1200;
7export const WORLD_YEAR_OFFSET = 1200;
shared/render/pivot.js added +31 −0
@@ -0,0 +1,31 @@
1 import { PIVOT_FROM_BOTTOM_PX } from "../protocol/constants.js";
2
3 export function tilePivot (tileX, tileY, tileSize)
4 {
5 return {
6 x: tileX * tileSize + tileSize / 2,
7 y: tileY * tileSize + tileSize / 2
8 };
9 }
10
11 export function spriteCenterFromPivot (pivotX, pivotY, spriteHeight, zoom)
12 {
13 const height = spriteHeight * zoom;
14 return {
15 x: pivotX,
16 y: pivotY - (height / 2 - PIVOT_FROM_BOTTOM_PX * zoom)
17 };
18 }
19
20 export function spriteDrawSize (spriteWidth, spriteHeight, zoom)
21 {
22 return {
23 w: spriteWidth * zoom,
24 h: spriteHeight * zoom
25 };
26 }
27
28 export function ySortLayer (sortY, subOrder)
29 {
30 return 10000 + Math.round(sortY) * 4 + subOrder;
31 }
@@ -0,0 +1,31 @@
1import { PIVOT_FROM_BOTTOM_PX } from "../protocol/constants.js";
2
3export function tilePivot (tileX, tileY, tileSize)
4{
5 return {
6 x: tileX * tileSize + tileSize / 2,
7 y: tileY * tileSize + tileSize / 2
8 };
9}
10
11export function spriteCenterFromPivot (pivotX, pivotY, spriteHeight, zoom)
12{
13 const height = spriteHeight * zoom;
14 return {
15 x: pivotX,
16 y: pivotY - (height / 2 - PIVOT_FROM_BOTTOM_PX * zoom)
17 };
18}
19
20export function spriteDrawSize (spriteWidth, spriteHeight, zoom)
21{
22 return {
23 w: spriteWidth * zoom,
24 h: spriteHeight * zoom
25 };
26}
27
28export function ySortLayer (sortY, subOrder)
29{
30 return 10000 + Math.round(sortY) * 4 + subOrder;
31}
tile_mmo_server_technical_design_v0.6.md +32 −33
@@ -57,7 +57,8 @@ format: living-design-document
57 57 - Build the player-facing client on the shared FrameworkV3 library, vendored
58 58 as a git submodule and built first so game-specific client code can layer
59 59 on top of it, while keeping the server-side ECS an implementation detail of
60 the backend. All world sprites are 16×16 pixels. The play viewport stays
60 the backend. World sprites may be any size; each uses a centred pivot
61 8 pixels from the sprite bottom. The play viewport stays
61 62 centered on the local player.
62 63
63 64 - Authoritative movement is tile-to-tile at a **global** walk/run cadence
@@ -602,7 +603,9 @@ players cannot walk onto it until an admin **opens** the chunk.
602 603 **Closed** chunks can still appear in a player's 3×3 view. They cannot be
603 604 entered: `MOVE_TO`, pathfinding, spawning, and other player-entry actions
604 605 treat every tile in a closed chunk as impassable. Visibility and lighting
605 previews are unchanged.
606 previews are unchanged. Where an **open** chunk shares an edge with a
607 closed (or never-edited) chunk, the client draws a red border on that
608 edge so players can see they cannot cross.
606 609
607 610 **Open** chunks are the playable map. Opening or closing is an authored
608 611 chunk flag, saved with the pending revision like paint.
@@ -1534,27 +1537,23 @@ but the client must not depend on the internal layout of ECS component storage.
1534 1537 That allows server internals to be optimised without forcing corresponding
1535 1538 client rewrites.
1536 1539
1537 ## 21.3 Sprites are 16×16
1540 ## 21.3 Sprite size, pivot and Y-sort
1538 1541
1539 Every world sprite — ground tiles, blocks, mobs, item icons and other
1540 in-world art — is exactly **16×16 pixels**. Sprites are not individually
1541 stretched to a different size. One sprite corresponds to one tile on the
1542 world pixel grid.
1542 World sprites may be any pixel size. The gameplay tile remains 16×16.
1543 Each sprite is placed with an automatic pivot: **horizontally centred**,
1544 and **8 pixels up from the bottom** of the sprite. That pivot sits on the
1545 tile centre, so a 16×16 sprite still fills the tile and a taller sprite
1546 stands on the same feet line and extends upward.
1543 1547
1544 At load time, any image whose width or height is not 16 is **rejected**.
1545 The asset must not enter the runtime atlas or definition registry. The
1546 failure should name the file and its actual dimensions.
1548 Blocks and mobiles with oversized sprites are **Y-sorted**: sprites
1549 higher on the screen draw behind sprites lower on the screen, using the
1550 pivot's world Y (the occupied tile, or the interpolated foot position
1551 while walking). Ground tiles and the night overlay stay behind and in
1552 front of that pass respectively.
1547 1553
1548 A unit test walks the sprite asset tree (grounds, blocks, mobs, items,
1549 equipment overlays, recolour masks, and any other world-sprite folders)
1550 and performs the same check. It reports every offender and **fails if any
1551 are found**. This test belongs in CI so a non-16×16 sprite cannot ship even
1552 if a local load path is skipped. Recolour masks are 16×16 world sprites
1553 too; a mismatched mask is a failed test.
1554
1555 Camera zoom (section 21.4) scales the whole viewport uniformly. It is not
1556 a per-sprite size override. Rendering should use nearest-neighbour
1557 sampling so 16×16 pixels stay sharp.
1554 Nearest-neighbour sampling still applies so pixels stay sharp under
1555 viewport zoom. Zoom scales the whole view uniformly; it is not a
1556 per-sprite size override.
1558 1557
1559 1558 ## 21.4 Viewport, camera and zoom
1560 1559
@@ -1585,8 +1584,8 @@ That lerp is presentation only:
1585 1584
1586 1585 ## 21.6 Equipment layers and recolouring
1587 1586
1588 A mob (including a player character) is drawn as a **stack of 16×16
1589 sprites** on the same tile: the body sprite (male or female from character
1587 A mob (including a player character) is drawn as a **stack of sprites**
1588 on the same tile: the body sprite (male or female from character
1590 1589 sex, or the mob archetype body), then each piece of visible equipment.
1591 1590 Overlays are not baked into the body art.
1592 1591
@@ -1602,8 +1601,8 @@ draw order (back → front, default)
1602 1601 ```
1603 1602
1604 1603 Slot draw order is data so a cloak or a two-handed sprite can be inserted
1605 without a renderer rewrite. Every overlay sprite, like every other world
1606 sprite, is exactly 16×16 and is rejected on load / CI if it is not.
1604 without a renderer rewrite. Overlay sprites use the same automatic pivot
1605 as other world art (horizontal centre, 8 pixels from the bottom).
1607 1606
1608 1607 Equipment items stay in dedicated **equipment slots**, not in the 32
1609 1608 inventory slots, while worn. `EquipItem(slotIndex)` moves a legal item
@@ -2883,7 +2882,7 @@ players; they do not buy player goods unless a later iteration adds that.
2883 2882 | Control | Human and future scripted control both emit validated action commands. |
2884 2883 | Deployment | The game exits gracefully; systemd relaunches it and only pulls/builds when an intentional deployment manifest requests it. |
2885 2884 | Client architecture | FrameworkV3 is a git submodule under `client/frameworkv3`, built before game client code; backend ECS internals do not become the client object model. |
2886 | Sprites | All world sprites are exactly 16×16 pixels; any other size is rejected on load and fails CI. Equipment overlays and recolour masks are included. |
2885 | Sprites | World sprites may be any size. Pivot is horizontal centre and 8px from the sprite bottom, on the tile centre. Blocks and mobiles Y-sort north-behind-south. |
2887 2886 | Appearance | Visible gear is layered 16×16 overlays on the mob; recolourable channels (such as metal) use material colour without duplicate art sets. Nearby clients receive appearance layers, not another player's inventory. |
2888 2887 | Play camera | The play viewport is centered on the local player. Only the admin world editor uses a free chunk camera. |
2889 2888 | Movement | All ground mobiles share a global walk/run cadence from world settings; the server commits integer tiles; clients lerp for presentation only. |
@@ -2948,9 +2947,9 @@ players; they do not buy player goods unless a later iteration adds that.
2948 2947 - Night shading must not light a tile the baked mask marks unreachable,
2949 2948 even if a torch is nearby through a wall.
2950 2949
2951 - A sprite whose pixel size is not 16×16 must be rejected at load and must
2952 fail the sprite-dimension unit test. Equipment overlays and recolour
2953 masks are included.
2950 - Oversized block and mob sprites must Y-sort so objects higher on the
2951 screen draw behind objects lower on the screen. Closed-chunk edges
2952 facing an open chunk must show a red border in the client.
2954 2953
2955 2954 - Equipping must not leave two items in the same equipment slot. Unequip
2956 2955 into a full inventory must fail and leave the item worn.
@@ -3076,10 +3075,10 @@ players; they do not buy player goods unless a later iteration adds that.
3076 3075 independently of backend ECS storage. The Node.js server does not import
3077 3076 FrameworkV3.
3078 3077
3079 - All world sprites (tiles, blocks, mobs, items) are exactly 16×16 pixels.
3080 Other sizes are rejected at load. A unit test lists offenders and fails if
3081 any exist. Sprites are not individually resized; the player may zoom the
3082 whole viewport within configured bounds.
3078 - World sprites may be any pixel size. Each is placed with a pivot at
3079 horizontal centre and 8 pixels from the sprite bottom, on the tile
3080 centre. Blocks and mobiles are Y-sorted. The player may zoom the whole
3081 viewport within configured bounds; sprites are not scaled individually.
3083 3082
3084 3083 - Visible equipment is drawn as extra 16×16 layers on the mob, including
3085 3084 players. Worn items occupy equipment slots, not the 32 inventory slots.
@@ -3297,7 +3296,7 @@ systemd → process supervision and relaunch
3297 3296 Deployment hook → conditional Git update/build only for intentional deployment restarts
3298 3297 Controller → manual client input today; sandboxed player scripts later
3299 3298 FrameworkV3 → git submodule at `client/frameworkv3`; built first; game client code layers on top
3300 Sprites → all world art is 16×16; reject and CI-fail any other size
3299 Sprites → any size; pivot at horizontal centre, 8px from bottom; Y-sort blocks/mobs
3301 3300 Equipment → layered 16×16 overlays on mobs; metal armour shares art and recolours by material
3302 3301 Camera → play view centered on the local player; bounded zoom; editor is chunk-framed
3303 3302 Movement → global walk/run cadence (default 2 tiles/s walk, run double); server tile steps; client visual lerp
@@ -57,7 +57,8 @@ format: living-design-document
57- Build the player-facing client on the shared FrameworkV3 library, vendored
57- Build the player-facing client on the shared FrameworkV3 library, vendored
58 as a git submodule and built first so game-specific client code can layer
58 as a git submodule and built first so game-specific client code can layer
59 on top of it, while keeping the server-side ECS an implementation detail of
59 on top of it, while keeping the server-side ECS an implementation detail of
60 the backend. All world sprites are 16×16 pixels. The play viewport stays
60 the backend. World sprites may be any size; each uses a centred pivot
61 8 pixels from the sprite bottom. The play viewport stays
61 centered on the local player.
62 centered on the local player.
62
63
63- Authoritative movement is tile-to-tile at a **global** walk/run cadence
64- Authoritative movement is tile-to-tile at a **global** walk/run cadence
@@ -602,7 +603,9 @@ players cannot walk onto it until an admin **opens** the chunk.
602**Closed** chunks can still appear in a player's 3×3 view. They cannot be
603**Closed** chunks can still appear in a player's 3×3 view. They cannot be
603entered: `MOVE_TO`, pathfinding, spawning, and other player-entry actions
604entered: `MOVE_TO`, pathfinding, spawning, and other player-entry actions
604treat every tile in a closed chunk as impassable. Visibility and lighting
605treat every tile in a closed chunk as impassable. Visibility and lighting
605previews are unchanged.
606previews are unchanged. Where an **open** chunk shares an edge with a
607closed (or never-edited) chunk, the client draws a red border on that
608edge so players can see they cannot cross.
606
609
607**Open** chunks are the playable map. Opening or closing is an authored
610**Open** chunks are the playable map. Opening or closing is an authored
608chunk flag, saved with the pending revision like paint.
611chunk flag, saved with the pending revision like paint.
@@ -1534,27 +1537,23 @@ but the client must not depend on the internal layout of ECS component storage.
1534That allows server internals to be optimised without forcing corresponding
1537That allows server internals to be optimised without forcing corresponding
1535client rewrites.
1538client rewrites.
1536
1539
1537## 21.3 Sprites are 16×16
1540## 21.3 Sprite size, pivot and Y-sort
1538
1541
1539Every world sprite — ground tiles, blocks, mobs, item icons and other
1542World sprites may be any pixel size. The gameplay tile remains 16×16.
1540in-world art — is exactly **16×16 pixels**. Sprites are not individually
1543Each sprite is placed with an automatic pivot: **horizontally centred**,
1541stretched to a different size. One sprite corresponds to one tile on the
1544and **8 pixels up from the bottom** of the sprite. That pivot sits on the
1542world pixel grid.
1545tile centre, so a 16×16 sprite still fills the tile and a taller sprite
1546stands on the same feet line and extends upward.
1543
1547
1544At load time, any image whose width or height is not 16 is **rejected**.
1548Blocks and mobiles with oversized sprites are **Y-sorted**: sprites
1545The asset must not enter the runtime atlas or definition registry. The
1549higher on the screen draw behind sprites lower on the screen, using the
1546failure should name the file and its actual dimensions.
1550pivot's world Y (the occupied tile, or the interpolated foot position
1551while walking). Ground tiles and the night overlay stay behind and in
1552front of that pass respectively.
1547
1553
1548A unit test walks the sprite asset tree (grounds, blocks, mobs, items,
1554Nearest-neighbour sampling still applies so pixels stay sharp under
1549equipment overlays, recolour masks, and any other world-sprite folders)
1555viewport zoom. Zoom scales the whole view uniformly; it is not a
1550and performs the same check. It reports every offender and **fails if any
1556per-sprite size override.
1551are found**. This test belongs in CI so a non-16×16 sprite cannot ship even
1552if a local load path is skipped. Recolour masks are 16×16 world sprites
1553too; a mismatched mask is a failed test.
1554
1555Camera zoom (section 21.4) scales the whole viewport uniformly. It is not
1556a per-sprite size override. Rendering should use nearest-neighbour
1557sampling so 16×16 pixels stay sharp.
1558
1557
1559## 21.4 Viewport, camera and zoom
1558## 21.4 Viewport, camera and zoom
1560
1559
@@ -1585,8 +1584,8 @@ That lerp is presentation only:
1585
1584
1586## 21.6 Equipment layers and recolouring
1585## 21.6 Equipment layers and recolouring
1587
1586
1588A mob (including a player character) is drawn as a **stack of 16×16
1587A mob (including a player character) is drawn as a **stack of sprites**
1589sprites** on the same tile: the body sprite (male or female from character
1588on the same tile: the body sprite (male or female from character
1590sex, or the mob archetype body), then each piece of visible equipment.
1589sex, or the mob archetype body), then each piece of visible equipment.
1591Overlays are not baked into the body art.
1590Overlays are not baked into the body art.
1592
1591
@@ -1602,8 +1601,8 @@ draw order (back → front, default)
1602```
1601```
1603
1602
1604Slot draw order is data so a cloak or a two-handed sprite can be inserted
1603Slot draw order is data so a cloak or a two-handed sprite can be inserted
1605without a renderer rewrite. Every overlay sprite, like every other world
1604without a renderer rewrite. Overlay sprites use the same automatic pivot
1606sprite, is exactly 16×16 and is rejected on load / CI if it is not.
1605as other world art (horizontal centre, 8 pixels from the bottom).
1607
1606
1608Equipment items stay in dedicated **equipment slots**, not in the 32
1607Equipment items stay in dedicated **equipment slots**, not in the 32
1609inventory slots, while worn. `EquipItem(slotIndex)` moves a legal item
1608inventory slots, while worn. `EquipItem(slotIndex)` moves a legal item
@@ -2883,7 +2882,7 @@ players; they do not buy player goods unless a later iteration adds that.
2883| Control | Human and future scripted control both emit validated action commands. |
2882| Control | Human and future scripted control both emit validated action commands. |
2884| Deployment | The game exits gracefully; systemd relaunches it and only pulls/builds when an intentional deployment manifest requests it. |
2883| Deployment | The game exits gracefully; systemd relaunches it and only pulls/builds when an intentional deployment manifest requests it. |
2885| Client architecture | FrameworkV3 is a git submodule under `client/frameworkv3`, built before game client code; backend ECS internals do not become the client object model. |
2884| Client architecture | FrameworkV3 is a git submodule under `client/frameworkv3`, built before game client code; backend ECS internals do not become the client object model. |
2886| Sprites | All world sprites are exactly 16×16 pixels; any other size is rejected on load and fails CI. Equipment overlays and recolour masks are included. |
2885| Sprites | World sprites may be any size. Pivot is horizontal centre and 8px from the sprite bottom, on the tile centre. Blocks and mobiles Y-sort north-behind-south. |
2887| Appearance | Visible gear is layered 16×16 overlays on the mob; recolourable channels (such as metal) use material colour without duplicate art sets. Nearby clients receive appearance layers, not another player's inventory. |
2886| Appearance | Visible gear is layered 16×16 overlays on the mob; recolourable channels (such as metal) use material colour without duplicate art sets. Nearby clients receive appearance layers, not another player's inventory. |
2888| Play camera | The play viewport is centered on the local player. Only the admin world editor uses a free chunk camera. |
2887| Play camera | The play viewport is centered on the local player. Only the admin world editor uses a free chunk camera. |
2889| Movement | All ground mobiles share a global walk/run cadence from world settings; the server commits integer tiles; clients lerp for presentation only. |
2888| Movement | All ground mobiles share a global walk/run cadence from world settings; the server commits integer tiles; clients lerp for presentation only. |
@@ -2948,9 +2947,9 @@ players; they do not buy player goods unless a later iteration adds that.
2948- Night shading must not light a tile the baked mask marks unreachable,
2947- Night shading must not light a tile the baked mask marks unreachable,
2949 even if a torch is nearby through a wall.
2948 even if a torch is nearby through a wall.
2950
2949
2951- A sprite whose pixel size is not 16×16 must be rejected at load and must
2950- Oversized block and mob sprites must Y-sort so objects higher on the
2952 fail the sprite-dimension unit test. Equipment overlays and recolour
2951 screen draw behind objects lower on the screen. Closed-chunk edges
2953 masks are included.
2952 facing an open chunk must show a red border in the client.
2954
2953
2955- Equipping must not leave two items in the same equipment slot. Unequip
2954- Equipping must not leave two items in the same equipment slot. Unequip
2956 into a full inventory must fail and leave the item worn.
2955 into a full inventory must fail and leave the item worn.
@@ -3076,10 +3075,10 @@ players; they do not buy player goods unless a later iteration adds that.
3076 independently of backend ECS storage. The Node.js server does not import
3075 independently of backend ECS storage. The Node.js server does not import
3077 FrameworkV3.
3076 FrameworkV3.
3078
3077
3079- All world sprites (tiles, blocks, mobs, items) are exactly 16×16 pixels.
3078- World sprites may be any pixel size. Each is placed with a pivot at
3080 Other sizes are rejected at load. A unit test lists offenders and fails if
3079 horizontal centre and 8 pixels from the sprite bottom, on the tile
3081 any exist. Sprites are not individually resized; the player may zoom the
3080 centre. Blocks and mobiles are Y-sorted. The player may zoom the whole
3082 whole viewport within configured bounds.
3081 viewport within configured bounds; sprites are not scaled individually.
3083
3082
3084- Visible equipment is drawn as extra 16×16 layers on the mob, including
3083- Visible equipment is drawn as extra 16×16 layers on the mob, including
3085 players. Worn items occupy equipment slots, not the 32 inventory slots.
3084 players. Worn items occupy equipment slots, not the 32 inventory slots.
@@ -3297,7 +3296,7 @@ systemd → process supervision and relaunch
3297Deployment hook → conditional Git update/build only for intentional deployment restarts
3296Deployment hook → conditional Git update/build only for intentional deployment restarts
3298Controller → manual client input today; sandboxed player scripts later
3297Controller → manual client input today; sandboxed player scripts later
3299FrameworkV3 → git submodule at `client/frameworkv3`; built first; game client code layers on top
3298FrameworkV3 → git submodule at `client/frameworkv3`; built first; game client code layers on top
3300Sprites → all world art is 16×16; reject and CI-fail any other size
3299Sprites → any size; pivot at horizontal centre, 8px from bottom; Y-sort blocks/mobs
3301Equipment → layered 16×16 overlays on mobs; metal armour shares art and recolours by material
3300Equipment → layered 16×16 overlays on mobs; metal armour shares art and recolours by material
3302Camera → play view centered on the local player; bounded zoom; editor is chunk-framed
3301Camera → play view centered on the local player; bounded zoom; editor is chunk-framed
3303Movement → global walk/run cadence (default 2 tiles/s walk, run double); server tile steps; client visual lerp
3302Movement → global walk/run cadence (default 2 tiles/s walk, run double); server tile steps; client visual lerp