A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
import { describe, expect, it } from 'vitest';
import { Bakes, finish, type WorkJob } from '../src/runtime/bakes';
function* counting(steps: number): WorkJob<string> {
for (let i = 0; i < steps; i++) yield i / steps;
return 'done';
}
/** A clock that moves a millisecond each time it is read. */
const ticking = (): (() => number) => { let t = 0; return () => t++; };
describe('jobs spread over frames', () => {
it('step for the budget of a frame, show their progress, and settle with what they made', async () => {
const bakes = new Bakes();
bakes.budgetMs = 3;
const job = bakes.run('Counting', counting(10));
bakes.step(ticking());
expect(bakes.active).toHaveLength(1);
expect(bakes.active[0]!.label).toBe('Counting');
expect(bakes.active[0]!.progress).toBeGreaterThan(0);
expect(bakes.active[0]!.progress).toBeLessThan(1);
for (let f = 0; f < 10; f++) bakes.step(ticking());
await expect(job.done).resolves.toBe('done');
expect(bakes.active).toHaveLength(0);
});
it('stop when cancelled, and show marks of work stepped elsewhere until they are done', () => {
const bakes = new Bakes();
const job = bakes.run('Never', counting(1000));
job.cancel();
expect(bakes.active).toHaveLength(0);
const owner = {};
bakes.mark(owner, 'Building', 0.25);
expect(bakes.active).toEqual([{ label: 'Building', progress: 0.25 }]);
bakes.mark(owner, 'Building', 1);
expect(bakes.active).toHaveLength(0);
});
it('reject when the job throws', async () => {
const bakes = new Bakes();
const job = bakes.run('Broken', (function* () { yield 0; throw new Error('no'); })());
bakes.step(ticking());
bakes.step(ticking());
await expect(job.done).rejects.toThrow('no');
});
it('run to their end at once for a caller with no frames', () => {
expect(finish(counting(5))).toBe('done');
});
});
/** A clock the test moves by hand. */
const manual = () => { let t = 0; return { now: () => t, spend: (ms: number) => { t += ms; } }; };
/** Works in 1 ms pieces for as long as it is given time, as the engine's steppers do: one piece whatever it is told (what stands by the
* player is made at once), then while it may. Returns how many it got through, which is that first piece and its part of the frame. */
const work = (bakes: Bakes, owner: object, clock: { spend(ms: number): void }, max = 1000): number => {
let done = 0;
do { clock.spend(1); done++; } while (done < max && bakes.hasTime(owner));
return done;
};
// The ground's far pages, asked first each frame, took the whole budget for half a minute while the chunks and the plants
// beside the player had none of it.
describe('the frame budget is shared', () => {
it('gives each of those that asked the frame before an equal part, whoever runs first', () => {
const bakes = new Bakes();
bakes.budgetMs = 9;
const clock = manual();
const terrain = {}, chunks = {}, plants = {};
// The first frame nobody is known yet, so the first to ask is given all of it.
bakes.step(clock.now);
expect(work(bakes, terrain, clock)).toBe(1 + 9);
work(bakes, chunks, clock); work(bakes, plants, clock);
// From then on each is expected, and the three share.
for (let frame = 0; frame < 3; frame++) {
bakes.step(clock.now);
expect([work(bakes, terrain, clock), work(bakes, chunks, clock), work(bakes, plants, clock)]).toEqual([1 + 3, 1 + 3, 1 + 3]);
}
});
it('passes on what one does not use to those after it', () => {
const bakes = new Bakes();
bakes.budgetMs = 9;
const clock = manual();
const terrain = {}, chunks = {}, plants = {};
bakes.step(clock.now);
work(bakes, terrain, clock); work(bakes, chunks, clock); work(bakes, plants, clock);
bakes.step(clock.now);
// The terrain has two pieces left to make and is done as soon as it has asked: the other two share nearly all of the frame,
// where a third each would have left three milliseconds unused. The chunks have 4.5 ms and stop at 4, a fifth piece not
// fitting; the plants have the 5 that leaves.
expect(work(bakes, terrain, clock, 2)).toBe(2);
expect(work(bakes, chunks, clock)).toBe(1 + 4);
expect(work(bakes, plants, clock)).toBe(1 + 5);
});
it('gives all of it back to one that is left asking alone', () => {
const bakes = new Bakes();
bakes.budgetMs = 8;
const clock = manual();
const terrain = {}, chunks = {};
bakes.step(clock.now);
work(bakes, terrain, clock); work(bakes, chunks, clock);
bakes.step(clock.now);
expect(work(bakes, terrain, clock)).toBe(1 + 4);
// The chunks are done and do not ask: the frame after, the terrain is alone.
bakes.step(clock.now);
expect(work(bakes, terrain, clock)).toBe(1 + 8);
});
it('never gives the work stepped elsewhere more than the frame has, however many ask', () => {
const bakes = new Bakes();
bakes.budgetMs = 8;
const clock = manual();
const owners = [{}, {}, {}, {}, {}];
bakes.step(clock.now);
for (const o of owners) work(bakes, o, clock);
for (let frame = 0; frame < 4; frame++) {
bakes.step(clock.now);
const before = clock.now();
for (const o of owners) work(bakes, o, clock);
// Each does one piece whatever it is told, so five owners may run a piece each past their part.
expect(clock.now() - before).toBeLessThanOrEqual(8 + owners.length);
}
});
});
describe('a piece that would not fit', () => {
// A cell of grass takes about as long to build as the whole steady budget. Asked only whether time was left, its stepper
// built two or three a frame.
it('is left for the next frame once the owner has had its one', () => {
const bakes = new Bakes();
bakes.budgetMs = 8;
const clock = manual();
const grass = {};
const cells = (): number => { let made = 0; while (bakes.hasTime(grass)) { clock.spend(8); made++; } return made; };
bakes.step(clock.now);
// The first frame it is not known how long a cell takes: the second ask finds time gone already.
expect(cells()).toBe(1);
for (let frame = 0; frame < 4; frame++) { bakes.step(clock.now); expect(cells()).toBe(1); }
});
it('still gives one piece to an owner whose part is smaller than a piece', () => {
const bakes = new Bakes();
bakes.budgetMs = 8;
const clock = manual();
const grass = {}, others = [{}, {}, {}];
const cells = (): number => { let made = 0; while (bakes.hasTime(grass)) { clock.spend(8); made++; } return made; };
// The first frame nobody is expected, and whoever asks first has all of it.
bakes.step(clock.now);
for (const o of others) work(bakes, o, clock);
cells();
for (let frame = 0; frame < 4; frame++) {
bakes.step(clock.now);
for (const o of others) work(bakes, o, clock);
// A quarter of the frame is 2 ms and a cell is 8: one is made all the same, or none ever would be.
expect(cells()).toBe(1);
}
});
it('fits as many small pieces as the part holds', () => {
const bakes = new Bakes();
bakes.budgetMs = 8;
const clock = manual();
const pages = {};
const made = (): number => { let n = 0; while (bakes.hasTime(pages)) { clock.spend(2); n++; } return n; };
bakes.step(clock.now); made();
bakes.step(clock.now);
expect(made()).toBe(4);
});
});
describe('work the player would see missing', () => {
it('is given more of the frame until it says it is done', () => {
const bakes = new Bakes();
bakes.budgetMs = 8;
bakes.priorityExtraMs = 12;
const clock = manual();
const chunks = {};
expect(bakes.urgent).toBe(false);
bakes.urge(chunks, true);
expect(bakes.urgent).toBe(true);
bakes.step(clock.now);
expect(work(bakes, chunks, clock)).toBe(1 + 20);
bakes.urge(chunks, false);
bakes.step(clock.now);
expect(work(bakes, chunks, clock)).toBe(1 + 8);
// An owner that goes away does not hold the frame at the larger budget.
bakes.urge(chunks, true);
bakes.clear(chunks);
expect(bakes.frameBudgetMs).toBe(8);
});
});
describe('an owner whose pieces are not alike', () => {
it('is held to its longest piece lately, not to a mean the empty ones pull down', () => {
const bakes = new Bakes();
bakes.budgetMs = 8;
const clock = manual();
const chunks = {};
// Five chunks wanted a frame: empty ones that cost nothing, and cells of grass at 8 ms each.
const frame = (costs: number[]): number => { let spent = 0; for (const c of costs) { if (!bakes.hasTime(chunks)) break; clock.spend(c); spent += c; } return spent; };
bakes.step(clock.now); frame([0, 0, 8, 0, 0]);
for (let f = 0; f < 6; f++) {
bakes.step(clock.now);
// One cell of grass a frame, whatever stands before it in the list.
expect(frame([0, 0, 8, 8, 8])).toBe(8);
}
});
});