@netforge/asset-library 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +60 -59
  2. package/package.json +21 -8
package/README.md CHANGED
@@ -1,74 +1,75 @@
1
1
  # @netforge/asset-library
2
2
 
3
- The per-style asset library of the Net Forge game engine: real CC0
4
- characters, creatures, vehicles, weapons, props and sprites, addressed by
5
- library id (`style.lowpoly.truck`), never by URL.
3
+ The CC0 game asset library of the Net Forge game engine: a manifest of real characters, creatures, vehicles, weapons, props, sprites and sounds, addressed by library id (`style.lowpoly.truck`) and never by URL, plus the shared rigs, the look composer, the example gallery and the three.js loader the templates draw with.
4
+
5
+ ## Install
6
6
 
7
7
  ```sh
8
- pnpm --filter @netforge/asset-library fetch-packs # download every pack from its official source into .cache
9
- pnpm --filter @netforge/asset-library test
10
- pnpm --filter @netforge/asset-library viewer # contact sheets at http://localhost:5480/?style=lowpoly
11
- CHROME_BIN=... pnpm --filter @netforge/asset-library shoot -- thumbs # gallery thumbnails
8
+ npm install @netforge/asset-library
9
+ ```
10
+
11
+ Node 20 or later. The package ships TypeScript source (ES modules), so use it through a bundler or a TypeScript-aware runtime. The built model and sound files are a separate package, `@netforge/asset-library-files`.
12
+
13
+ ## Example
14
+
15
+ ```ts
16
+ import { assetById, idsForStyle, search, soundBank } from "@netforge/asset-library";
17
+
18
+ idsForStyle("lowpoly").length; // every stocked lowpoly id
19
+ search("lowpoly", "a ghost", 3).map((h) => h.asset.id); // ids that match a description
20
+ assetById("style.lowpoly.ghost")?.kind; // "creature"
21
+ const sounds = soundBank("./library"); // { cues, music } URLs for the engine's SoundPlayer
22
+ ```
23
+
24
+ Drawing a model in a template client (three.js):
25
+
26
+ ```ts
27
+ import { createRenderer } from "@netforge/engine/runtime";
28
+ import { LibraryClient } from "@netforge/asset-library/three";
29
+
30
+ const handle = await createRenderer(canvas);
31
+ const lib = new LibraryClient(handle, { baseUrl: "./library" });
32
+ const hero = await lib.character("style.lowpoly.hooded_adventurer", { tint: "#ffd27a" });
33
+ scene.add(hero.root);
12
34
  ```
13
35
 
14
- The optimized library (`.glb`/`.png` files, thumbnails and `index.json`) is
15
- built by the Net Forge asset pipeline, which is not part of this package.
16
- The built files ship as `@netforge/asset-library-files`; copy its
17
- `library/` folder to `packages/asset-library/.library` to use the viewer and
18
- `shoot` here, or pass that folder as `dir` to the Vite plugin.
36
+ Serving the files in a Vite build:
37
+
38
+ ```ts
39
+ import { assetLibrary } from "@netforge/asset-library/vite";
19
40
 
20
- ## What is in git, and what is not
41
+ export default { plugins: [assetLibrary({ dir: "node_modules/@netforge/asset-library-files/library" })] };
42
+ ```
21
43
 
22
- - In git: `manifest/` (packs with licence and verification, one JSON per
23
- style, the gallery), `NOTICE`, `LICENSES/`, the fetch script, and a
24
- three-file fixture subset in `fixtures/`.
25
- - Not in git: `.cache/` (pack archives and source files) and `.library/`
26
- (optimized `.glb`/`.png`, thumbnails, `index.json`). Both are gitignored.
27
- After one fetch the asset pipeline rebuilds the library with no network.
44
+ ## Entry points
28
45
 
29
- ## Stock today
46
+ | Import | What it holds |
47
+ |---|---|
48
+ | `@netforge/asset-library` | the manifest and lookups (`library`, `assetById`, `idsForStyle`, `search`, `referenceableIds`, `galleryFor`), looks (`resolveLook`), rigs and clips (`RIGS`, `CLIPS`, `clipFor`), paths (`assetPath`, `libraryUrl`), sounds (`soundBank`, `cueSounds`, `musicTracks`), `restyleId` and `modelGuide` |
49
+ | `@netforge/asset-library/three` | `LibraryClient` (loads through the engine's `AssetLoader` with meshopt and KTX2), `RigAnimator`, `bakeCrowd`, `prepareModel`, `proceduralAsset` |
50
+ | `@netforge/asset-library/vite` | `assetLibrary(options)`: serves the library at `./library` in dev and copies only the models a game uses into its build |
51
+ | `@netforge/asset-library/gallery` | ready-made looks per style, with a name, a line and a thumbnail |
52
+
53
+ ## What is in it
30
54
 
31
55
  | Style | Assets | Sources |
32
56
  |---|---|---|
33
57
  | `lowpoly` (3D) | 228 | Quaternius (animated characters, monsters, animals, dinosaurs, robots, tanks, weapons, props) and Kenney (Mini and Blocky Characters, Car, Blaster, Nature, Space, Food and City kits) |
34
58
  | `pixel` (2D) | 52 | Kenney Tiny Dungeon, Pixel Platformer, Pixel Vehicle Pack |
35
59
 
36
- `toon`, `voxel`, `ps1` and `handdrawn` have a slot in the schema and no
37
- stock yet. A style is one JSON manifest plus its packs; nothing else changes.
38
-
39
- Audio (`manifest/audio.json`, style `audio`): 17 CC0 sound effects from
40
- Kenney's Impact, Interface, RPG, Sci-fi and Digital Audio packs, one per
41
- FeelKit cue (hit, impact, kill, bigKill, hurt, levelUp, gem, coin, dash,
42
- step, land, boss, ui, pick, downed, revive, shoot), and one CC0 music loop,
43
- "Battle Theme A" by cynicmusic
44
- (https://opengameart.org/content/battle-theme-a). Same rules as models:
45
- licence verified per pack, bytes pinned by sha256, files only in `.cache`
46
- and `.library` (`.library/audio/<sfx|music>/<name>.<ogg|mp3>`). `soundBank(base)`
47
- turns it into the cue -> URL map the engine's `SoundPlayer` loads; each
48
- entry's `gain` is its default mix level.
49
-
50
- ## Pieces
51
-
52
- - **Manifest** (`src/schema.ts`, `manifest/*.json`): every asset has an id,
53
- kind, body plan, rig, source (archive path or pinned per-file URL with its
54
- licence page), height, one plain line for the model, search tags, and the
55
- aliases older drafts used. Variants (`monster_truck` = the truck on big
56
- wheels) and procedural pickups (gems, cells) are entries too.
57
- - **Shared rigs** (`src/rigs.ts`): Kenney's humanoids share one node set and
58
- clip set; Quaternius models share one naming family. Canonical clips are
59
- idle, walk, run, jump, attack, shoot, hit, die, with fallbacks; body plans
60
- (biped, quadruped, flyer, blob, wheeled, static) drive crowd motion.
61
- - **Appearances** (`src/look.ts`, engine `src/api/appearance.ts`): the internal composer
62
- the builder uses to turn a description into an original: a library base,
63
- a tint that shifts the palette, an accent, a scale, and up to four parts.
64
- Creators never see it; they describe or pick from the gallery.
65
- - **Gallery** (`manifest/gallery.ts`, plain data Net Forge bundles): ready-made looks per style with a
66
- name, a line and a thumbnail; Net Forge's "pick a starting look".
67
- - **Runtime** (`src/three/`): `LibraryClient` loads through the engine's
68
- `AssetLoader` (meshopt, KTX2), prepares models (face -z, scale, tint,
69
- parts), animates characters with the engine's `AnimatedCharacter` through
70
- the shared rigs (`RigAnimator`), and bakes crowds into static parts the
71
- engine's `AnimatedCrowd` animates (bob, waddle, squash, flash). Baking real
72
- clips into VAT crowds (`bakeVertexAnimation`) is the next step.
73
- - **Build plugin** (`src/vite.ts`): serves `.library` at `./library` in dev
74
- and copies only the models a game uses into its build.
60
+ - `toon`, `voxel`, `ps1` and `handdrawn` have a slot in the schema. A style is one JSON manifest plus its packs.
61
+ - Audio: 17 CC0 sound effects from Kenney's Impact, Interface, RPG, Sci-fi and Digital Audio packs, one per feel cue (hit, impact, kill, bigKill, hurt, levelUp, gem, coin, dash, step, land, boss, ui, pick, downed, revive, shoot), and one CC0 music loop, "Battle Theme A" by cynicmusic.
62
+ - Every asset has an id, a kind, a body plan, a rig, a pinned source with its licence page, a height, one plain description line, search tags and the aliases older drafts used.
63
+ - Shared rigs: Kenney's humanoids share one node and clip set, and Quaternius models share one naming family. Canonical clips are idle, walk, run, jump, attack, shoot, hit and die, with fallbacks.
64
+ - Appearances: a library base plus a tint, an accent, a scale and up to four parts make an original look.
65
+
66
+ Game code never imports this package. It names assets by id in `src/game.ts` (for example `prefab("shade", { model: "style.lowpoly.ghost" })`), and the template loads them.
67
+
68
+ ## Docs
69
+
70
+ - https://forge.netnet.capital/docs/packages/asset-library
71
+ - `NOTICE` lists every pack, its licence and where the licence was verified.
72
+
73
+ ## License
74
+
75
+ The code is MIT (see `LICENSE`). The art in the manifest is third-party work released under CC0 1.0 (see `NOTICE` and `LICENSES/`).
package/package.json CHANGED
@@ -1,14 +1,26 @@
1
1
  {
2
2
  "name": "@netforge/asset-library",
3
- "version": "0.1.0",
4
- "description": "The per-style asset library of the Net Forge game engine: a manifest of CC0 models and sprites addressed by library id, shared rigs and clip sets, the look composer, the example gallery, and the three.js loader the templates draw with.",
3
+ "version": "0.2.0",
4
+ "description": "CC0 game asset library for Net Forge: a manifest of models, sprites and sounds addressed by library id, shared rigs, the look composer and a three.js loader.",
5
+ "keywords": [
6
+ "game-assets",
7
+ "cc0",
8
+ "threejs",
9
+ "three",
10
+ "game-engine",
11
+ "browser-game",
12
+ "gamedev",
13
+ "typescript",
14
+ "net-forge"
15
+ ],
5
16
  "license": "MIT",
6
17
  "type": "module",
7
18
  "exports": {
8
19
  ".": "./src/index.ts",
9
20
  "./three": "./src/three/index.ts",
10
21
  "./vite": "./src/vite.ts",
11
- "./gallery": "./manifest/gallery.ts"
22
+ "./gallery": "./manifest/gallery.ts",
23
+ "./package.json": "./package.json"
12
24
  },
13
25
  "files": [
14
26
  "src",
@@ -20,15 +32,19 @@
20
32
  "LICENSES",
21
33
  "LICENSE"
22
34
  ],
35
+ "sideEffects": false,
23
36
  "publishConfig": {
24
37
  "access": "public"
25
38
  },
39
+ "homepage": "https://forge.netnet.capital/docs/packages/asset-library",
40
+ "bugs": {
41
+ "url": "https://github.com/netnetdev/net-forge/issues"
42
+ },
26
43
  "repository": {
27
44
  "type": "git",
28
45
  "url": "git+https://github.com/netnetdev/net-forge.git",
29
46
  "directory": "packages/asset-library"
30
47
  },
31
- "homepage": "https://github.com/netnetdev/net-forge/tree/main/packages/asset-library#readme",
32
48
  "engines": {
33
49
  "node": ">=20"
34
50
  },
@@ -36,7 +52,7 @@
36
52
  "fflate": "0.8.3",
37
53
  "three": "0.186.1",
38
54
  "zod": "4.4.3",
39
- "@netforge/engine": "0.1.0"
55
+ "@netforge/engine": "0.2.0"
40
56
  },
41
57
  "devDependencies": {
42
58
  "@types/node": "22.20.1",
@@ -46,9 +62,6 @@
46
62
  "vite": "6.4.3",
47
63
  "vitest": "3.2.7"
48
64
  },
49
- "bugs": {
50
- "url": "https://github.com/netnetdev/net-forge/issues"
51
- },
52
65
  "scripts": {
53
66
  "typecheck": "tsc -p tsconfig.json",
54
67
  "test": "vitest run",