arcane-engine 0.26.1

Arcane game engine — agent-native 2D engine with embedded TypeScript runtime
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98

# Assets

> **No assets?** For procedural graphics without image files (backgrounds, UI, effects, prototyping), see [sdf.md](sdf.md). SDF shapes are resolution-independent and defined entirely in code.

## Finding Assets with Skills

Use the built-in skills to browse and setup game assets:

```
/sprite      # Open sprite catalog browser
/sound       # Open sound catalog browser
```

The skills will:
1. Launch `arcane catalog` which opens a visual browser UI
2. Let you download packs, browse, and select sprites/sounds
3. Generate ready-to-use TypeScript code from your selections
4. Copy assets from cache to your project's `assets/` directory

## Built-in Asset Catalog

Arcane includes a built-in catalog of CC0 (public domain) game assets, primarily from **Kenney.nl**. Assets are downloaded to `~/.cache/arcane/packs/` and then copied to your project.

All assets are CC0 — use freely in any project.

## Manual Asset Setup

If you prefer to set up assets manually:

### Sprites with Atlas Loader

```typescript
import { loadAtlasFromDef } from "@arcane/runtime/rendering";

// Define sprites (coordinates from catalog or measured manually)
const atlas = loadAtlasFromDef({
  id: "my-sprites",
  primarySheet: "spritesheet.png",
  sheetWidth: 512,
  sheetHeight: 512,
  sprites: {
    "player": { x: 0, y: 0, w: 32, h: 32 },
    "enemy": { x: 32, y: 0, w: 32, h: 32 },
    "coin": { x: 64, y: 0, w: 16, h: 16 },
  },
}, { basePath: "assets/" });

// Draw sprites (centered at position)
atlas.draw("player", { x: 100, y: 200, scale: 2 });
atlas.draw("enemy", { x: 300, y: 200 });
atlas.draw("coin", { x: 150, y: 180, layer: 5 });
```

### Individual Textures

```typescript
import { loadTexture, drawSprite } from "@arcane/runtime/rendering";

const playerTex = loadTexture("assets/player.png");

drawSprite({
  textureId: playerTex,
  x: 100, y: 200,
  w: 32, h: 32,
  layer: 1,
});
```

### Sounds

```typescript
import { loadSound, playSound, playMusic } from "@arcane/runtime/rendering";

const jumpSfx = loadSound("assets/sounds/jump.wav");
const bgMusic = loadSound("assets/music/theme.ogg");

playSound(jumpSfx, { volume: 0.8 });
playMusic("assets/music/theme.ogg", 0.5);
```

## Path Resolution

Asset paths are resolved relative to your entry file:

```
my-game/
├── src/
│   └── visual.ts      # Entry file
├── assets/
│   ├── sprites/
│   └── sounds/
```

From `src/visual.ts`, use `../assets/sprites/player.png` or use absolute paths.

## Caching & Preloading

Both `loadTexture()` and `loadSound()` cache by path — calling multiple times returns the same handle. For loading screens, use `preloadAssets(paths)` and check `getLoadingProgress()` (0.0 to 1.0).