setup
setup(
options):object
Defined in: webgpu/setup.ts:341
Initializes the WebGPU simulation for a given canvas and automaton. The grid is randomly initialized
with the defined elements unless an initialGrid is provided.
Use index found in ElementBlueprint instances to reference elements when building the initialGrid.
Parameters
Section titled “Parameters”options
Section titled “options”An object containing the canvas element and the compiled automaton.
automaton
Section titled “automaton”Automaton
The compiled automaton produced by vivarium().create().
canvas
Section titled “canvas”HTMLCanvasElement
The HTML canvas element. Its width and height define the grid dimensions.
initialGrid?
Section titled “initialGrid?”number[] | number[][]
An optional 2d array of element indices to use instead of random initialization. Alternatively, you can pass a flat (1d) array with one index per cell, row-major order.
Returns
Section titled “Returns”An object with:
update— advances the simulation by one step (synchronous, GPU only).draw— reads the latest GPU state and renders it to the canvas (async).evolve— convenience shorthand forupdate()+await draw().readGrid— reads the current grid state.writeCell— updates a single cell by flat index.writeCellAt— updates a single cell by grid coordinates.writeGrid— overwrites the entire grid.setAutomaton— replaces the automaton rules.tgpuRoot— the underlying TypeGPU root.
draw()
Section titled “draw()”draw: () =>
Promise<void>
Reads the latest simulation state from the GPU and renders it to the canvas.
Must be called after at least one update call.
This function is asynchronous because it waits for the GPU to finish processing before reading the result.
Returns
Section titled “Returns”Promise<void>
evolve()
Section titled “evolve()”evolve: () =>
Promise<void>
Convenience function that advances the simulation by one step and draws
the result. Equivalent to calling update() followed by await draw().
Returns
Section titled “Returns”Promise<void>
readGrid()
Section titled “readGrid()”readGrid: () =>
Promise<number[]>
Reads the current grid state from the GPU and returns a flat array of element indices.
Returns
Section titled “Returns”Promise<number[]>
setAutomaton()
Section titled “setAutomaton()”setAutomaton: (
__namedParameters) =>void
Parameters
Section titled “Parameters”__namedParameters
Section titled “__namedParameters”automaton
Section titled “automaton”Automaton
Returns
Section titled “Returns”void
tgpuRoot
Section titled “tgpuRoot”tgpuRoot:
TgpuRoot=root
update()
Section titled “update()”update: () =>
void
Advances the simulation by one step on the GPU. This function is synchronous — it only queues GPU commands without waiting for them to complete.
Call update as many times as needed to run multiple simulation steps,
then call draw once to render the latest state to the canvas.
Returns
Section titled “Returns”void
writeCell()
Section titled “writeCell()”writeCell: (
index,elementIndex) =>void
Writes a single cell in the current grid, updating both its element index and color.
Parameters
Section titled “Parameters”number
The flat index of the cell to update (row-major order).
elementIndex
Section titled “elementIndex”number
The element index to assign to the cell.
Returns
Section titled “Returns”void
writeCellAt()
Section titled “writeCellAt()”writeCellAt: (
x,y,elementIndex) =>void
Writes a single cell by grid coordinates, updating both its element index and color.
Parameters
Section titled “Parameters”number
The column of the cell (0-based, from left).
number
The row of the cell (0-based, from top).
elementIndex
Section titled “elementIndex”number
The element index to assign to the cell.
Returns
Section titled “Returns”void
writeGrid()
Section titled “writeGrid()”writeGrid: (
grid) =>void
Overwrites the entire grid with the given flat array of element indices, updating both the ids and colors buffers. Useful for restoring a snapshot or painting the grid in bulk.
Parameters
Section titled “Parameters”number[]
A flat array of element indices (row-major order) whose length must equal width * height.
Returns
Section titled “Returns”void