Public: anyone can read this; the crew can change it.

Migrated from github.com/amirmushichge/pixel-plays

Town layout: a tested `town.js` that places one isometric building per game and picks the building under a point #142

Merged opened this

Check · Review · Land · Live done — Landed and live in production.

Merged

torque/pixel-plays:torque/132-town-layout-a-tested-town-js-that-places → main 2 commits fork 4 threads · 4 unresolved

  • Merged. torque/132-town-layout-a-tested-town-js-that-places was merged into main as db45970.

Review

Sign in to review this change.
3 files changed +234 −0
README.md +1
@@ -71,6 +71,7 @@ Every page carries Open Graph and Twitter tags (between `og:begin` and `og:end`)
7171 ## Add a game
7272 Create `<id>/index.html`, load `../shell.js`, call `PixelPlays.mount({ id, rules })`, set `window.PP_SCENE`, load `../engine.js`, then add the game to `GAMES` in `shell.js` with a one-line `blurb`; the home page lists every `GAMES` entry as a card with its `kind`, `input` and `accent`, searchable and filterable by kind (a static fallback list for no-JS is kept in sync by `serve.test.mjs`, so add the matching `<li>` to `index.html` too, with the same `data-kind`, `data-input`, `--accent` and tags line). Then run `bun scripts/og.mjs` to make its share card and tags. The page needs a `#mute` button. Put its background track at `<id>/<id>.mp3`, or set `music: false` on its `GAMES` entry when it has none (Stone Skip, Kite Hill, Paper Route, Harbour Crane, Pizza Toss, Sled Run, Pottery Wheel, Row Home, Orchard, Lighthouse, Market Scale, Window Washer, Domino Run, Campfire, Beekeeper, Bread Oven, Ice Fishing, Tightrope, Tram Line, Archery, Bell Tower, Espresso Bar, Goalkeeper, Wood Split, Signal Box, Soapbox Derby, Sheepdog, Firefly Jar, Hot Air Balloon, Cloakroom, Empire Age, Egg Basket, Dinghy Race and Coconut Shy play on their own sound effects). Rules that need testing go in a plain script with a `.test.mjs` beside it, as in `kite-hill/model.js`.
7373
74 - `town.js` is the town's layout, pure data with no drawing: `window.PixelTown.layout(GAMES)` gives one isometric building per game (plot, screen position under the fixed 30-degree camera, accent, id) with trees in the spare plots, and `pick(town, x, y, filter)` gives the id of the front-most building under a screen point, or null. Nothing loads it yet; the drawing and the page are the second half of #99.
7475 - `shell.js` provides the game menu, the Rules popup, the credits and the background music. The menu lists the games grouped under their kind (the not-yet-made ones last, under Soon) and scrolls within the screen; type in its find box to narrow it by a word of the title, kind, input or blurb (keys typed there never reach the game), and press Escape to close it.
7576 - `engine.js` provides the camera, depth buffer, colour ramps, shadows, edges, figures, trees and wind as globals.
7677 - A game supplies its own `groundColor`, `bake`, `update` and `draw`.
town.js added +98
@@ -0,0 +1,98 @@
1 'use strict';
2 // Town layout: one isometric building per game, trees in the spare plots, and a pick under a screen point.
3 // Pure data in, plain data out: no drawing, no DOM. Loaded in a page it sets window.PixelTown; under bun it is the module's export.
4 (() => {
5 // Fixed 30-degree camera (dimetric "isometric" as drawn in pixel art): a grid step along x goes right and down,
6 // a step along y goes left and down. For a plot edge of TILE units:
7 // sx = (gx - gy) * TILE * cos(30deg) sy = (gx + gy) * TILE * sin(30deg) - elevation
8 const TILE = 64;
9 const COS = Math.cos(Math.PI / 6), SIN = Math.sin(Math.PI / 6);
10 const HALF_W = TILE * COS; // half the width of a plot's diamond, screen units
11 const HALF_H = TILE * SIN; // half its height
12 const FOOTPRINT = 0.8; // a building fills this share of its plot's edge, so streets show between them
13
14 // FNV-1a: a stable 32-bit hash of the id, so heights and tree shapes never depend on the list around them
15 function hash(s) {
16 let h = 0x811c9dc5;
17 for (let i = 0; i < s.length; i++) h = Math.imul(h ^ s.charCodeAt(i), 0x01000193) >>> 0;
18 return h;
19 }
20
21 // The fixed order plots are handed out in, independent of how many games there are: the origin, then square rings
22 // around it, each ring walked in (x, y) order. The Nth game always gets the Nth plot, so appending never moves anyone.
23 function plotAt(n) {
24 if (n === 0) return { gx: 0, gy: 0, ring: 0 };
25 let r = 1;
26 while ((2 * r + 1) ** 2 <= n) r++;
27 let k = n - (2 * r - 1) ** 2; // index inside ring r
28 const side = 2 * r + 1;
29 // ring r in (x, y) order: the two full columns x = -r and x = r, and between them the cells y = -r and y = r
30 if (k < side) return { gx: -r, gy: k - r, ring: r };
31 k -= side;
32 if (k < side) return { gx: r, gy: k - r, ring: r };
33 k -= side;
34 const x = Math.floor(k / 2) - r + 1;
35 return { gx: x, gy: k % 2 ? r : -r, ring: r };
36 }
37
38 const project = (gx, gy) => ({ x: (gx - gy) * HALF_W, y: (gx + gy) * HALF_H });
39
40 // games: [{ id, accent, soon? }]. Returns { buildings, trees, tile }.
41 // building: { id, accent, plot: {gx, gy}, x, y (screen position of the plot centre on the ground), depth, height, soon }
42 function layout(games) {
43 const list = Array.isArray(games) ? games : [];
44 const ids = new Set(), plots = new Set();
45 const buildings = [];
46 for (const g of list) {
47 if (!g || typeof g.id !== 'string' || ids.has(g.id)) continue; // a repeated id gets no second building
48 ids.add(g.id);
49 const p = plotAt(buildings.length);
outdated

The same Set holds id: keys and gx,gy keys. Use ids and plots, so the intent is plain and the two cannot collide.

50 const s = project(p.gx, p.gy);
51 plots.add(p.gx + ',' + p.gy);
52 buildings.push({
53 id: g.id, accent: typeof g.accent === 'string' ? g.accent : '#888888',
54 plot: { gx: p.gx, gy: p.gy }, x: s.x, y: s.y, depth: p.gx + p.gy,
55 height: 36 + hash(g.id) % 49, soon: !!g.soon,
56 });
57 }
58 // trees fill every free plot out to the outermost ring in use, plus one ring of margin when there are any buildings
59 const trees = [];
60 const reach = buildings.length ? plotAt(buildings.length - 1).ring + 1 : 0; // plots are handed out ring by ring, so the last one is the outermost
61 for (let n = 0; buildings.length && n < (2 * reach + 1) ** 2; n++) {
62 const p = plotAt(n);
63 if (plots.has(p.gx + ',' + p.gy)) continue;
64 const s = project(p.gx, p.gy);
65 const h = hash(p.gx + ',' + p.gy);
66 trees.push({ plot: { gx: p.gx, gy: p.gy }, x: s.x, y: s.y, depth: p.gx + p.gy, height: 20 + h % 17, kind: h % 3 });
67 }
68 return { buildings, trees, tile: { halfWidth: HALF_W, halfHeight: HALF_H } };
69 }
70
71 // Is the screen point inside the building's drawn silhouette: a box whose ground and roof are diamonds,
72 // i.e. the roof diamond, the ground diamond and the rectangle joining their side corners.
73 function covers(b, px, py) {
74 const w = HALF_W * FOOTPRINT, h = HALF_H * FOOTPRINT;
75 const dx = Math.abs(px - b.x);
76 if (dx > w) return false;
77 const diamond = cy => Math.abs(py - cy) <= h * (1 - dx / w);
78 const roofY = b.y - b.height;
79 return diamond(b.y) || diamond(roofY) || (py >= roofY && py <= b.y);
80 }
outdated

covers is the pick's core, yet no test hits the ground-diamond-only, the roof-diamond-only or the bounding-box-corner cases. Add them.

81
82 // The id of the front-most building under the point, or null. Front is the larger gx + gy (nearer the camera);
83 // the later plot wins a tie. `filter(building)` returning false takes a building out of the running.
84 function pick(town, px, py, filter) {
85 if (!town || !Array.isArray(town.buildings) || !Number.isFinite(px) || !Number.isFinite(py)) return null;
86 let best = null;
87 for (const b of town.buildings) {
88 if (typeof filter === 'function' && !filter(b)) continue;
89 if (!covers(b, px, py)) continue;
90 if (!best || b.depth >= best.depth) best = b;
91 }
92 return best ? best.id : null;
93 }
94
95 const api = { layout, pick, plotAt, TILE };
96 if (typeof module !== 'undefined' && module.exports) module.exports = api;
outdated

project is exported but used by no caller or test. Remove it from the API.

97 if (typeof window !== 'undefined') window.PixelTown = api;
98 })();
town.test.mjs added +135
@@ -0,0 +1,135 @@
1 import { test, expect } from 'bun:test';
2 import town from './town.js';
3
4 const { layout, pick, plotAt, TILE } = town;
5 const games = n => Array.from({ length: n }, (_, i) => ({ id: 'g' + i, accent: '#' + String(100000 + i) }));
6 const byId = (t, id) => t.buildings.find(b => b.id === id);
7
8 test('one building per game, with id and accent carried over', () => {
9 const t = layout(games(26));
10 expect(t.buildings.map(b => b.id)).toEqual(games(26).map(g => g.id));
11 expect(byId(t, 'g3').accent).toBe('#100003');
12 });
13
14 test('no two buildings, and no tree, share a plot', () => {
15 const t = layout(games(40));
16 const keys = [...t.buildings, ...t.trees].map(o => o.plot.gx + ',' + o.plot.gy);
17 expect(new Set(keys).size).toBe(keys.length);
18 expect(t.trees.length).toBeGreaterThan(0);
19 });
20
21 test('the same list gives the same town', () => {
22 expect(layout(games(12))).toEqual(layout(games(12)));
23 });
24
25 test('appending a game moves no existing building', () => {
26 const a = layout(games(9)), b = layout(games(10));
27 for (const x of a.buildings) expect(byId(b, x.id)).toEqual(x);
28 expect(b.buildings.length).toBe(10);
29 });
30
31 test('screen position follows the 30-degree camera (hand calculation)', () => {
32 const t = layout(games(3));
33 const b = byId(t, 'g1'); // second plot: ring 1, first cell (-1, -1), straight up the screen
34 expect(b.plot).toEqual({ gx: -1, gy: -1 });
35 expect(b.x).toBeCloseTo(0, 9);
36 expect(b.y).toBeCloseTo(-2 * TILE * 0.5, 9);
37 const c = byId(t, 'g2'); // (-1, 0): left of the origin by TILE*cos30, up by TILE*sin30
38 expect(c.plot).toEqual({ gx: -1, gy: 0 });
39 expect(c.x).toBeCloseTo(-TILE * Math.cos(Math.PI / 6), 9);
40 expect(c.y).toBeCloseTo(-TILE * 0.5, 9);
41 });
42
43 test('plots are handed out in a fixed order with no repeats', () => {
44 const seen = new Set();
45 for (let n = 0; n < 200; n++) { const p = plotAt(n); seen.add(p.gx + ',' + p.gy); }
46 expect(seen.size).toBe(200);
47 });
48
49 test('a repeated id or a malformed entry gets no building', () => {
50 const t = layout([{ id: 'a' }, { id: 'a' }, null, { title: 'x' }, { id: 'b' }]);
51 expect(t.buildings.map(b => b.id)).toEqual(['a', 'b']);
52 expect(layout(undefined).buildings).toEqual([]);
53 });
54
55 test('a pick in front beats one behind', () => {
56 // build two overlapping buildings by hand: same screen spot, different depth
57 const manual = { buildings: [
58 { id: 'near', x: 0, y: 0, depth: 3, height: 50 },
59 { id: 'far', x: 0, y: -30, depth: 1, height: 50 },
60 ] };
61 expect(pick(manual, 0, -20)).toBe('near');
62 expect(pick({ buildings: [...manual.buildings].reverse() }, 0, -20)).toBe('near');
63 expect(pick(manual, 0, -79)).toBe('far'); // above the near roof, still inside the far one
64 });
65
66 test('a pick on empty ground is null', () => {
67 const t = layout(games(5));
68 expect(pick(t, 5000, 5000)).toBeNull();
69 expect(pick(t, NaN, 0)).toBeNull();
70 expect(pick(null, 0, 0)).toBeNull();
71 });
72
73 test('a pick on a building gives its id, and a filtered-out building is never picked', () => {
74 const t = layout(games(1));
75 const b = t.buildings[0];
76 expect(pick(t, b.x, b.y - b.height / 2)).toBe('g0');
77 expect(pick(t, b.x, b.y - b.height / 2, x => x.id !== 'g0')).toBeNull();
78 const two = { buildings: [{ id: 'near', x: 0, y: 0, depth: 3, height: 50 }, { id: 'far', x: 0, y: 0, depth: 1, height: 50 }] };
79 expect(pick(two, 0, -20, x => x.id !== 'near')).toBe('far');
80 });
81
82 test('soon is carried through and an entry without an accent gets the default', () => {
83 const t = layout([{ id: 'a', soon: true, accent: '#123456' }, { id: 'b' }, { id: 'c', accent: 7 }]);
84 expect(t.buildings.map(b => b.soon)).toEqual([true, false, false]);
85 expect(t.buildings.map(b => b.accent)).toEqual(['#123456', '#888888', '#888888']);
outdated

orig is never changed, so this restore is a no-op, and window stays defined for later tests. Capture the real previous values and delete globalThis.window in a finally.

86 });
87
88 test('trees reach one ring beyond the outermost building, and an empty list has none', () => {
89 expect(layout([]).trees).toEqual([]);
90 expect(layout(games(1)).buildings.length).toBe(1);
91 const ringOf = o => Math.max(Math.abs(o.plot.gx), Math.abs(o.plot.gy));
92 for (const n of [1, 2, 9, 10, 25, 26]) {
93 const t = layout(games(n));
94 const outer = Math.max(...t.buildings.map(ringOf));
95 expect(Math.max(...t.trees.map(ringOf))).toBe(outer + 1);
96 expect(t.trees.length + n).toBe((2 * outer + 3) ** 2);
97 }
98 });
99
100 test('heights stay within 36..84 and depend only on the id', () => {
101 const t = layout(games(200));
102 for (const b of t.buildings) { expect(b.height).toBeGreaterThanOrEqual(36); expect(b.height).toBeLessThanOrEqual(84); }
103 const alone = layout([{ id: 'g77' }]).buildings[0];
104 expect(byId(t, 'g77').height).toBe(alone.height);
105 expect(new Set(t.buildings.map(b => b.height)).size).toBeGreaterThan(10);
106 });
107
108 // a building at the origin, height 50: ground diamond about y = 0, roof diamond about y = -50,
109 // each 0.8 * 55.4 wide (44.3) and 0.8 * 32 high (25.6) from the centre
110 test('the silhouette is the ground diamond, the roof diamond and the box between', () => {
111 const one = { buildings: [{ id: 'a', x: 0, y: 0, depth: 0, height: 50 }] };
112 const at = (x, y) => pick(one, x, y);
113 expect(at(0, 20)).toBe('a'); // ground diamond only: below the box, inside the diamond
114 expect(at(0, -50 - 20)).toBe('a'); // roof diamond only: above the box
115 expect(at(0, 40)).toBeNull(); // below the ground diamond
116 expect(at(0, -50 - 40)).toBeNull(); // above the roof diamond
117 expect(at(40, 20)).toBeNull(); // corner of the bounding box under the side corner: outside the diamond
118 expect(at(40, -50 - 20)).toBeNull(); // the same at the roof
119 expect(at(40, -25)).toBe('a'); // the box between the diamonds reaches the full width
120 expect(at(50, -25)).toBeNull(); // but no wider
121 });
122
123 test('works on the real GAMES list', async () => {
124 const saved = { window: globalThis.window, document: globalThis.document };
125 globalThis.window = globalThis;
126 try {
127 await import('./shell.js?town');
128 const g = window.PixelPlays.GAMES;
129 const t = layout(g);
130 expect(t.buildings.length).toBe(new Set(g.map(x => x.id)).size);
131 } finally {
132 for (const [k, v] of Object.entries(saved)) { if (v === undefined) delete globalThis[k]; else globalThis[k] = v; }
133 delete globalThis.PixelPlays;
134 }
135 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs