sg.js API Reference

Complete reference for the SiliconGhetto engine JavaScript API (sg.js).

import sg from 'https://cdn.siliconghetto.com/engine/v0.1/sg.js';

Lifecycle

sg.init(canvasId, width, height) — async

Initialize the engine. Loads the WASM module, detects GPU (WebGPU or WebGL2 fallback), and sets up the rendering context.

await sg.init('game-canvas', 800, 600);

sg.run({ update, draw })

Start the game loop. update() runs at 60fps for game logic. draw() runs after for rendering.

sg.run({
    update() { /* game logic */ },
    draw() { /* rendering */ },
});

sg.stop()

Stop the game loop.

sg.clear(r, g, b)

Set the background clear color. Call at the start of draw().

sg.clear(0.1, 0.1, 0.2); // dark blue

Time

Input

Keyboard

Key names use KeyboardEvent.code values: 'KeyW', 'ArrowUp', 'Space', 'ShiftLeft', etc.

if (sg.keyDown('KeyW')) { /* moving forward */ }
if (sg.keyPressed('Space')) { /* just jumped */ }

Mouse

Entities (2D)

sg.spawn(opts) → number

Create an entity. Returns a numeric handle used to reference the entity in all other calls.

const player = sg.spawn({
    x: 400, y: 300,
    sprite: { w: 32, h: 32, r: 1, g: 0.3, b: 0.3 },
    collision: { w: 32, h: 32 },
    tag: 'player',
});

sg.despawn(entity)

Remove an entity and clean up all subsystem state (health, physics, AI, animation).

Position & Velocity

Appearance

Tags

Camera

Drawing

Call these inside draw(). All coordinates are screen-space pixels.

sg.drawRect(10, 10, 200, 30, { r: 0, g: 0, b: 0, a: 0.5 });
sg.drawText('Score: 100', 15, 15, 14, { r: 1, g: 1, b: 1 });

Screen

Physics (2D)

Collision Detection

Platformer Physics

Full platformer controller with gravity, jumping (coyote time + jump buffer), and variable jump height.

const player = sg.spawn({ x: 100, y: 100, collision: { w: 16, h: 24 } });
sg.setPlatformerPhysics(player, {
    gravity: 980, jumpForce: 400, maxFall: 600, speed: 200,
});

// In update():
const input = sg.keyDown('ArrowRight') ? 1 : sg.keyDown('ArrowLeft') ? -1 : 0;
if (sg.keyPressed('Space')) sg.platformerJump(player);
sg.platformerJumpHeld(player, sg.keyDown('Space'));

const { dx, dy } = sg.updatePlatformer(player, input);
const { hitX, hitY } = sg.tilemapCollide(sg.getX(player), sg.getY(player), 8, 12, dx, dy);
sg.platformerResolve(player, hitX, hitY, dy > 0);

Top-Down Physics

sg.setTopDownPhysics(entity, { speed: 150, friction: 600 });

Tile Maps

Grid-based level system with collision.

sg.createTileMap(20, 15, 32); // 20x15 grid, 32px tiles
sg.setTile(5, 14, 1);         // solid ground
sg.setTileFlags(3, 10, 2, 2); // platform (one-way)

// In draw():
sg.drawTileMap();

Animation

Frame-based sprite animation system.

sg.addAnimation(player, 'run', { frames: [0, 1, 2, 3], fps: 10, loop: true });
sg.addAnimation(player, 'idle', { frames: [0], fps: 1 });
sg.playAnim(player, 'run');

// In draw():
const frame = sg.getAnimFrame(player); // current frame index

Health & Damage

sg.setHealth(enemy, 50);        // 50 HP
sg.damage(enemy, 20);           // -20 HP, triggers invincibility
sg.heal(enemy, 10);             // +10 HP (capped at max)

if (sg.isDead(enemy)) sg.despawn(enemy);

Projectiles

const bullet = sg.spawnProjectile(x, y, 1, 0, 300, {
    damage: 25, lifetime: 2, owner: player,
    w: 8, h: 4, r: 1, g: 0.8, b: 0,
});

// In update():
sg.updateProjectiles();
for (const { handle, damage } of sg.checkProjectileHits()) {
    sg.damage(handle, damage);
}

// In draw():
sg.drawProjectiles();

AI Behaviors

sg.setAI(enemy, 'chase', { target: player, speed: 80 });
sg.setAI(guard, 'patrol', { points: [[100,200], [300,200]], speed: 60 });
sg.setAI(rabbit, 'flee', { target: player, speed: 120, maxDistance: 200 });

// In update():
for (const { handle, dx, dy, facing } of sg.updateAI()) {
    const { hitX, hitY } = sg.tilemapCollide(sg.getX(handle), sg.getY(handle), 8, 12, dx, dy);
    sg.setPos(handle, sg.getX(handle) + (hitX ? 0 : dx), sg.getY(handle) + (hitY ? 0 : dy));
}

Voxel World

Quick Start

const { seed } = await sg.createVoxelGame({
    canvas: 'game-canvas',
    worldSize: [256, 64, 256],
    seed: 42,
});

sg.run({
    update() { sg.fpsUpdate(); },
    draw() { sg.clear(0.5, 0.7, 1.0); },
});

sg.createVoxelGame(opts) — async

One-call setup: initializes engine, creates voxel world, generates terrain with 20 biomes, enables FPS controller, sets up pointer lock.

Returns { seed, canvas, width, height }.

Block Operations

Block Types

Access via sg.BLOCKS or sg.blockTypes:

sg.setBlock(x, y, z, sg.BLOCKS.STONE);
sg.setBlock(x, y, z, sg.BLOCKS.DIAMOND_ORE);

Block names are available via sg.BLOCK_NAMES[id].

FPS Controller

Enabled automatically by createVoxelGame(), or manually:

sg.enableFPSController({
    speed: 7,             // walk speed
    jumpForce: 8.5,       // jump velocity
    gravity: 22,          // gravity strength
    sensitivity: 0.003,   // mouse look sensitivity
    flySpeed: 14,         // fly mode speed
    sprintMultiplier: 1.6,// shift sprint
    playerRadius: 0.28,   // collision cylinder radius
    playerHeight: 1.65,   // collision cylinder height
});

Built-in controls: WASD (move), Mouse (look), Space (jump), Shift (sprint), F (fly toggle), Ctrl (fly down).

Raycasting

DDA (Digital Differential Analyzer) — exact, never misses a block.

// From FPS eye position:
const hit = sg.voxelRaycast(7);
if (hit.hit) {
    // hit.x, hit.y, hit.z — the block that was hit
    // hit.prevX, hit.prevY, hit.prevZ — the air block before it (for placing)
    // hit.blockType — block type ID
}

// From arbitrary position + direction:
const hit2 = sg.voxelRaycastFrom(ox, oy, oz, dx, dy, dz, 20);

Collision

Terrain Generation

sg.generateTerrain({ seed: 42 });

Generates terrain using simplex noise with 20 biomes, 3 cave types (cheese, spaghetti, noodle), Y-level ore distribution, biome-specific trees, and surface decoration (flowers, grass).

Biome System

20 default biomes are registered automatically. To customize:

// Replace all biomes with custom set:
sg.resetBiomes();
sg.addBiome({
    name: 'Alien Desert',
    tempRange: [0.5, 1.0],
    moistRange: [-1, 0],
    surface: sg.BLOCKS.RED_SAND,
    subSurface: sg.BLOCKS.TERRACOTTA,
    treeDensity: 0.02,
    treeTrunk: sg.BLOCKS.CACTUS,
    treeLeaves: sg.BLOCKS.AIR,
});
sg.generateTerrain({ seed: 42 });

Assets

await sg.loadTexture('hero', 'hero.png');
await sg.loadSound('jump', 'jump.wav');

sg.drawSprite('hero', 100, 200, 32, 32);
sg.playSound('jump');

CDN Library

await sg.loadTexture('hero', sg.lib.texture('hero-spritesheet'));
await sg.loadSound('jump', sg.lib.sound('jump'));

Particles

const emitter = sg.createEmitter(400, 300);
sg.emitBurst(emitter, 50); // spawn 50 particles

3D Meshes

const cube = sg.createCube();
const sphere = sg.createSphere();
const plane = sg.createPlane();