@natterjs/assets 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,40 @@
+MIT License
+
+Copyright (c) 2026 Julian Dorn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+-------------------------------------------------------------------------------
+Third-party code
+
+packages/core/src/fdlibm.js is a port of fdlibm as adapted in V8:
+
+  Copyright (C) 1993 by Sun Microsystems, Inc. All rights reserved.
+  Developed at SunSoft, a Sun Microsystems, Inc. business.
+  Permission to use, copy, modify, and distribute this software is freely
+  granted, provided that this notice is preserved.
+
+  The V8 adaptation is Copyright 2016 the V8 project authors (BSD-style license).
+
+packages/core/src/stdlib/npziggurat.js contains the ziggurat tables of numpy
+(numpy/random/src/distributions/ziggurat_constants.h), Copyright (c) NumPy
+Developers, BSD 3-Clause License.
+
+The images and sounds in packages/assets are covered by
+packages/assets/LICENSE-ASSETS.md, not by this license.

package/LICENSE-ASSETS.md

@@ -0,0 +1,28 @@
+# License of the images and sounds
+
+This applies to the images (`*/*.png`, `turtle/*.svg`), the sounds (`sounds/*.wav`) and the lists (`*/pack.json`,
+`sounds/sounds.json`, `catalog.json`, `gametypes.json`) in this package. The small JavaScript file `index.js` is
+code and falls under the MIT license in `LICENSE`.
+
+## Intended license: CC0 1.0
+
+The library is meant to be **CC0 1.0 Universal** (public domain dedication,
+<https://creativecommons.org/publicdomain/zero/1.0/>): free to use, change and pass on, also commercially and
+without attribution. This is how `README.md`, `CONVENTIONS.md` and the developer notes (`DEVELOPMENT.md`, „Gedacht als CC0“, in the repository) of this package describe it.
+
+## Origin
+
+- **Images (PNG):** drawn for this project by an image model (`google/gemini-3.1-flash-image` through OpenRouter)
+  from the project's own prompts, with `scripts/asset-gen/style-emoji.png` as style reference, then cut and keyed
+  with `scripts/asset-gen/keyslice.py`. The prompts of each pack are in `<pack>/make.py` in the repository. Every
+  result was checked so that none imitates an existing game, film or brand character.
+- **Turtle shapes (SVG):** `turtle/turtle.svg` and `turtle/turtle_side.svg`, simple shapes written as SVG code
+  directly in this repository (added in commit `def8b41`); no external source is recorded for them.
+- **Sounds (WAV):** synthesised by `scripts/gen-sounds.py` (deterministic, no recordings or samples).
+
+## Third-party material
+
+None. The repository records no image or sound from a third-party source (no external sprite or sound packs), so
+no attribution is required.
+
+Source: <https://github.com/wi-wissen/Natter/tree/main/packages/assets>

package/README.md

@@ -1,3 +1,79 @@
-# Temporary Holding Version
+# @natterjs/assets
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Images and sounds for Python games in [Natter](https://natter.wi7.net/) and [CodeNatter](https://codenatter.de): more than 900 PNG sprites in one consistent flat emoji style, two SVG turtle shapes and 14 short sounds, sorted into packs (platformer, space, sea, animals, puzzles, adventure, user interface …) and described in one `catalog.json`. Students write only a name, without uploading files:
+
+```python
+heroine = Actor("heroine_run_1")
+screen.blit("pf_grass_mid", (0, 416))
+sounds.coin.play()
+```
+
+Browse every image and sound in the [sprite gallery](https://natter.wi7.net/sprites/).
+
+## Install
+
+```bash
+npm install @natterjs/assets
+```
+
+## Usage
+
+The package is meant to be served as it is (from jsDelivr, unpkg or a copy of the folder on your own server). `index.js` gives the URLs relative to itself:
+
+```js
+import { assetsOption, baseUrl, catalogUrl, gametypesUrl } from '@natterjs/assets';
+
+assetsOption();          // { baseUrl, catalog: 'catalog.json' }: the whole library
+assetsOption(['space']); // { baseUrl, catalog: 'catalog.json', packs: ['space'] }: only these packs
+baseUrl;                 // folder of the library, ends with '/'; an image is at baseUrl + 'space/sp_ship.png'
+```
+
+Pass `assetsOption()` as the `assets` option of `createPgzero` or `createKara` from [`@natterjs/web`](https://www.npmjs.com/package/@natterjs/web):
+
+```js
+import { createRunner, createPgzero } from 'https://cdn.jsdelivr.net/npm/@natterjs/web@0.1.0/dist/natter-web.js';
+import { assetsOption } from 'https://cdn.jsdelivr.net/npm/@natterjs/assets@0.1.0/index.js';
+
+const runner = createRunner();
+const pgz = createPgzero(document.querySelector('#game'), { assets: assetsOption(), lang: 'en' });
+runner.use(pgz);
+await pgz.run(runner, 'ship = Actor("sp_ship", (400, 300))\n\ndef draw():\n    screen.clear()\n    ship.draw()');
+```
+
+When a bundler copies the package files elsewhere, serve the folder yourself and pass its address instead: `{ baseUrl: 'https://example.org/assets/', catalog: 'catalog.json' }`. Without a bundler or npm, use the jsDelivr folder directly as `baseUrl`: `https://cdn.jsdelivr.net/npm/@natterjs/assets@0.1.0/` (always pin a version).
+
+### How names map to files
+
+- Every image and sound has a unique name across all packs (`^[a-z][a-z0-9_]*$`). The catalog lists it with its pack and file: `heroine_run_1` → `characters/heroine_run_1.png`, `coin` → `sounds/coin.wav`.
+- **Pygame Zero:** `Actor("name")`, `screen.blit("name", …)`, `images.name` and `sounds.name` look the name up in the catalog. The host reads the catalog once and then loads only the files a program names; a string like `"heroine_run_" + str(i)` loads all names starting with `heroine_run_`. A file of the same name in the project's `images/` or `sounds/` folder always wins.
+- **Kara:** the world is drawn with the images of the `kara` pack (`kara`, `kara_up`, `kara_left`, `kara_down`, `kara_tree`, `kara_blueberry`, `kara_mushroom`, `kara_grass` …). Replacing an image of that name in the catalog changes Kara's look; without assets Kara draws vector shapes.
+- **Animations:** frames end in `_<n>`, counted from 1 (`heroine_run_1` … `heroine_run_8`), all frames of one animation have the same size. Characters face right unless the name says `_left`.
+
+### Files
+
+| File | Content |
+|---|---|
+| `catalog.json` | All images (name, pack, path, width × height, bytes, tags, English and German description), all sounds (with length in seconds), the animation groups and the game types |
+| `gametypes.json` | The library sorted by kind of game, with a hand-picked starter set for each |
+| `<pack>/pack.json` | One pack: title, files, tags, descriptions |
+| `<pack>/*.png`, `turtle/*.svg`, `sounds/*.wav` | The images and sounds (about 4.5 MB in total) |
+
+Packs: `adventure`, `animals`, `arcade`, `book` (pond game with German names such as `ente`, `kueken`), `characters`, `flyer`, `grid_action`, `grid_chars`, `grid_puzzle`, `grid_tiles`, `kara`, `nature`, `platformer`, `sea`, `space`, `turtle`, `ui`, `sounds`.
+
+## Features
+
+- One style for everything, so packs fit together in one game.
+- Animation frames of the same size and aligned (feet at the same height).
+- Every image is listed with size, tags and an English and German description, ready for search and pickers.
+- Loads lazily: hosts fetch the catalog once and only the files a program uses.
+
+## Links
+
+- Sprite gallery: <https://natter.wi7.net/sprites/>
+- Website: <https://natter.wi7.net/>, command reference: <https://natter.wi7.net/reference/>
+- Source and issues: <https://github.com/wi-wissen/Natter>
+- [CodeNatter](https://codenatter.de): a browser IDE for learning Python in school, built on Natter.
+
+## License
+
+Images, sounds and the JSON lists are intended as **CC0 1.0** (public domain dedication): free to use, change and share, also commercially and without attribution. They are original work drawn from the project's own prompts and do not imitate existing game, film or brand characters; the sounds are synthesised. Details and origin: `LICENSE-ASSETS.md`. The small `index.js` is code under the MIT license (`LICENSE`).