Add world tile, chunk, and region coordinate helpers.
Co-authored-by: Cursor <cursoragent@cursor.com>
@@ -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 fi9
9
10
## World coordinates and spatial hierarchy10
## World coordinates and spatial hierarchy11
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 layers16
## Ground and block tile layers17
17
@@ -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 @@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,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 @@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
chunkKey11
} 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
});