BlueGit

timfa questward

Add world tile, chunk, and region coordinate helpers.

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

timfa Tim Falken · pushed by timfa

Authored 2026-08-24 · 2 months ago

Hash
d70631cb3afada3ec08b22a7d6a21e196b4df69c
Parent
7425ef06
3 files changed +116 −2
docs/FEATURES.md +2 −2
@@ -9,9 +9,9 @@ Each entry is a short note on behaviour and where the code lives. Update this fi
9 9
10 10 ## World coordinates and spatial hierarchy
11 11
12 **Status:** not implemented
12 **Status:** full
13 13 **Spec:** World tile coordinates are canonical. Chunks are 16×16 tiles; regions are 4×4 chunks. Negative coordinates use true floor division.
14 **Code:** —
14 **Code:** `server/src/world/coordinates.js`, tests in `server/tests/coordinates.test.js`
15 15
16 16 ## Ground and block tile layers
17 17
@@ -9,9 +9,9 @@ Each entry is a short note on behaviour and where the code lives. Update this fi
9
9
10## World coordinates and spatial hierarchy
10## World coordinates and spatial hierarchy
11
11
12**Status:** not implemented
12**Status:** full
13**Spec:** World tile coordinates are canonical. Chunks are 16×16 tiles; regions are 4×4 chunks. Negative coordinates use true floor division.
13**Spec:** World tile coordinates are canonical. Chunks are 16×16 tiles; regions are 4×4 chunks. Negative coordinates use true floor division.
14**Code:** —
14**Code:** `server/src/world/coordinates.js`, tests in `server/tests/coordinates.test.js`
15
15
16## Ground and block tile layers
16## Ground and block tile layers
17
17
server/src/world/coordinates.js added +83 −0
@@ -0,0 +1,83 @@
1 import { CHUNK_SIZE, REGION_CHUNKS } from "../../../shared/protocol/constants.js";
2
3 export function floorDiv (value, divisor)
4 {
5 return Math.floor(value / divisor);
6 }
7
8 export function tileToChunk (tile)
9 {
10 return floorDiv(tile, CHUNK_SIZE);
11 }
12
13 export function chunkToRegion (chunk)
14 {
15 return floorDiv(chunk, REGION_CHUNKS);
16 }
17
18 export function chunkOriginTile (chunk)
19 {
20 return chunk * CHUNK_SIZE;
21 }
22
23 export function tileToLocal (tile)
24 {
25 return ((tile % CHUNK_SIZE) + CHUNK_SIZE) % CHUNK_SIZE;
26 }
27
28 export function localToTile (chunk, local)
29 {
30 return chunkOriginTile(chunk) + local;
31 }
32
33 export function tileIndex (localX, localY)
34 {
35 return localY * CHUNK_SIZE + localX;
36 }
37
38 export function indexToLocal (index)
39 {
40 return {
41 localX: index % CHUNK_SIZE,
42 localY: Math.floor(index / CHUNK_SIZE)
43 };
44 }
45
46 export function chunkKey (chunkX, chunkY)
47 {
48 return `${chunkX},${chunkY}`;
49 }
50
51 export function parseChunkKey (key)
52 {
53 const [chunkX, chunkY] = key.split(",").map(Number);
54 return { chunkX, chunkY };
55 }
56
57 export function tileKey (tileX, tileY)
58 {
59 return `${tileX},${tileY}`;
60 }
61
62 export function visibleChunkCoords (chunkX, chunkY, radius = 1)
63 {
64 const coords = [];
65 for (let dy = -radius; dy <= radius; dy++)
66 {
67 for (let dx = -radius; dx <= radius; dx++)
68 {
69 coords.push({ chunkX: chunkX + dx, chunkY: chunkY + dy });
70 }
71 }
72 return coords;
73 }
74
75 export function chebyshevChunks (chunkX, chunkY, chunkRadius)
76 {
77 return visibleChunkCoords(chunkX, chunkY, chunkRadius);
78 }
79
80 export function maxLightChunkRadius (lightRangeTiles)
81 {
82 return Math.ceil(Math.max(0, lightRangeTiles) / CHUNK_SIZE);
83 }
@@ -0,0 +1,83 @@
1import { CHUNK_SIZE, REGION_CHUNKS } from "../../../shared/protocol/constants.js";
2
3export function floorDiv (value, divisor)
4{
5 return Math.floor(value / divisor);
6}
7
8export function tileToChunk (tile)
9{
10 return floorDiv(tile, CHUNK_SIZE);
11}
12
13export function chunkToRegion (chunk)
14{
15 return floorDiv(chunk, REGION_CHUNKS);
16}
17
18export function chunkOriginTile (chunk)
19{
20 return chunk * CHUNK_SIZE;
21}
22
23export function tileToLocal (tile)
24{
25 return ((tile % CHUNK_SIZE) + CHUNK_SIZE) % CHUNK_SIZE;
26}
27
28export function localToTile (chunk, local)
29{
30 return chunkOriginTile(chunk) + local;
31}
32
33export function tileIndex (localX, localY)
34{
35 return localY * CHUNK_SIZE + localX;
36}
37
38export function indexToLocal (index)
39{
40 return {
41 localX: index % CHUNK_SIZE,
42 localY: Math.floor(index / CHUNK_SIZE)
43 };
44}
45
46export function chunkKey (chunkX, chunkY)
47{
48 return `${chunkX},${chunkY}`;
49}
50
51export function parseChunkKey (key)
52{
53 const [chunkX, chunkY] = key.split(",").map(Number);
54 return { chunkX, chunkY };
55}
56
57export function tileKey (tileX, tileY)
58{
59 return `${tileX},${tileY}`;
60}
61
62export function visibleChunkCoords (chunkX, chunkY, radius = 1)
63{
64 const coords = [];
65 for (let dy = -radius; dy <= radius; dy++)
66 {
67 for (let dx = -radius; dx <= radius; dx++)
68 {
69 coords.push({ chunkX: chunkX + dx, chunkY: chunkY + dy });
70 }
71 }
72 return coords;
73}
74
75export function chebyshevChunks (chunkX, chunkY, chunkRadius)
76{
77 return visibleChunkCoords(chunkX, chunkY, chunkRadius);
78}
79
80export function maxLightChunkRadius (lightRangeTiles)
81{
82 return Math.ceil(Math.max(0, lightRangeTiles) / CHUNK_SIZE);
83}
server/tests/coordinates.test.js added +31 −0
@@ -0,0 +1,31 @@
1 import test from "node:test";
2 import assert from "node:assert/strict";
3 import { CHUNK_SIZE, REGION_CHUNKS } from "../../shared/protocol/constants.js";
4 import {
5 floorDiv,
6 tileToChunk,
7 chunkToRegion,
8 tileToLocal,
9 localToTile,
10 chunkKey
11 } from "../src/world/coordinates.js";
12
13 test("true floor division for negative coordinates", () =>
14 {
15 assert.equal(floorDiv(-1, CHUNK_SIZE), -1);
16 assert.equal(tileToChunk(-1), -1);
17 assert.equal(tileToLocal(-1), 15);
18 assert.equal(localToTile(-1, 15), -1);
19 assert.equal(chunkToRegion(-1), -1);
20 assert.equal(chunkToRegion(-4), -1);
21 assert.equal(chunkToRegion(-5), -2);
22 });
23
24 test("chunk and region sizes match the design", () =>
25 {
26 assert.equal(CHUNK_SIZE, 16);
27 assert.equal(REGION_CHUNKS, 4);
28 assert.equal(tileToChunk(16), 1);
29 assert.equal(chunkToRegion(4), 1);
30 assert.equal(chunkKey(2, -3), "2,-3");
31 });
@@ -0,0 +1,31 @@
1import test from "node:test";
2import assert from "node:assert/strict";
3import { CHUNK_SIZE, REGION_CHUNKS } from "../../shared/protocol/constants.js";
4import {
5 floorDiv,
6 tileToChunk,
7 chunkToRegion,
8 tileToLocal,
9 localToTile,
10 chunkKey
11} from "../src/world/coordinates.js";
12
13test("true floor division for negative coordinates", () =>
14{
15 assert.equal(floorDiv(-1, CHUNK_SIZE), -1);
16 assert.equal(tileToChunk(-1), -1);
17 assert.equal(tileToLocal(-1), 15);
18 assert.equal(localToTile(-1, 15), -1);
19 assert.equal(chunkToRegion(-1), -1);
20 assert.equal(chunkToRegion(-4), -1);
21 assert.equal(chunkToRegion(-5), -2);
22});
23
24test("chunk and region sizes match the design", () =>
25{
26 assert.equal(CHUNK_SIZE, 16);
27 assert.equal(REGION_CHUNKS, 4);
28 assert.equal(tileToChunk(16), 1);
29 assert.equal(chunkToRegion(4), 1);
30 assert.equal(chunkKey(2, -3), "2,-3");
31});