@nanonomad/characters

The shared character asset library for the NanoNomad digital pet. Contains the SVG poses, CSS stylesheets, and character.json configuration files for all built-in characters, along with URL helper utilities for resolving asset paths from npm or a CDN.

It is installed automatically with @nanonomad/react, @nanonomad/web, or manually with @nanonomad/core.

Installation

npm install @nanonomad/characters

Prefer npm install @nanonomad/react or npm install @nanonomad/web if you want a single top-level dependency.

Included characters

| ID | Name | Capabilities | |---|---|---| | default | Cat | idle, walk, jump, sit, fall | | dog | Doggo | idle, walk, run, jump, sit, sleep, pee, fall |

Each character includes a set of SVG pose files, a CSS stylesheet with color variables, and a character.json that defines its physics, behavior states, and color palette.

Serving assets

The NanoNomad engine fetches character assets at runtime using fetch(). You need to make those files reachable by the browser. There are two approaches.

Option 1 — Copy files into your project (recommended)

Use the included CLI tool to copy character files into your project's public folder:

npx nanonomad-characters-copy ./public/nanonomad-characters

This places all characters under public/nanonomad-characters/ with the following structure:

public/
  nanonomad-characters/
    pet.css
    registry.json
    default/
      character.json
      default.css
      default-front.svg
      default-side.svg
      default-sit.svg
      default-fall.svg
    dog/
      character.json
      dog.css
      dog-front.svg
      dog-side.svg
      dog-jump.svg
      dog-sleep.svg
      dog-pee.svg

You can also add this as a project script to keep assets in sync after package updates:

{
  "scripts": {
    "sync:pet": "nanonomad-characters-copy ./public/nanonomad-characters"
  }
}

Environment variables for install-time behavior:

| Variable | Effect | |---|---| | NANONOMAD_AUTO_COPY=1 | Automatically copies assets to ./public/nanonomad-characters during npm install, no prompt. | | NANONOMAD_SKIP_POSTINSTALL=1 | Suppresses the install-time prompt entirely. Copy manually when needed. |

Option 2 — Use the jsDelivr CDN

After @nanonomad/characters is published to npm, jsDelivr mirrors it automatically. No configuration is needed — URLs are live within a few minutes of each release.

Use the URL helpers from this package to generate the correct paths:

import { getCharacterUrls, getCoreStylesheetUrl, getCharacterStylesheetUrl } from '@nanonomad/characters'

const urls = getCharacterUrls('default', { version: '1.0.3' })
// {
//   character: 'default',
//   characterBaseUrl: 'https://cdn.jsdelivr.net/npm/@nanonomad/[email protected]/assets/default/',
//   characterConfigUrl: 'https://cdn.jsdelivr.net/npm/@nanonomad/[email protected]/assets/default/character.json'
// }

const petCssUrl = getCoreStylesheetUrl({ version: '1.0.3' })
// 'https://cdn.jsdelivr.net/npm/@nanonomad/[email protected]/assets/pet.css'

const characterCssUrl = getCharacterStylesheetUrl('default', { version: '1.0.3' })
// 'https://cdn.jsdelivr.net/npm/@nanonomad/[email protected]/assets/default/default.css'

URL helper API

All helpers accept an optional options object with a version property. When version is omitted, the helper uses the version of the installed package automatically.

getCharacterUrls(characterId, options?)

Returns the characterBaseUrl and characterConfigUrl values needed by the NanoNomad engine runtime config. This is the primary helper you will use.

import { getCharacterUrls } from '@nanonomad/characters'

const urls = getCharacterUrls('dog', { version: '1.0.3' })
// {
//   character: 'dog',
//   characterBaseUrl: 'https://cdn.jsdelivr.net/npm/@nanonomad/[email protected]/assets/dog/',
//   characterConfigUrl: 'https://cdn.jsdelivr.net/npm/@nanonomad/[email protected]/assets/dog/character.json'
// }

Spread the result directly into a runtime config:

import NanoNomad, { createBrowserHost } from '@nanonomad/core'
import { getCharacterUrls } from '@nanonomad/characters'

const pet = new NanoNomad({
  host: createBrowserHost(window),
  runtimeConfig: {
    ...getCharacterUrls('dog', { version: '1.0.3' }),
    movementSpeed: 70,
  },
})

getCoreStylesheetUrl(options?)

Returns the CDN URL for pet.css, which contains the base layout rules for the pet's overlay container. Load this before any character-specific stylesheet.

import { getCoreStylesheetUrl } from '@nanonomad/characters'

getCoreStylesheetUrl({ version: '1.0.3' })
// 'https://cdn.jsdelivr.net/npm/@nanonomad/[email protected]/assets/pet.css'

getCharacterStylesheetUrl(characterId, options?)

Returns the CDN URL for a character's CSS file. This stylesheet contains the CSS custom property definitions that drive color customization.

import { getCharacterStylesheetUrl } from '@nanonomad/characters'

getCharacterStylesheetUrl('dog', { version: '1.0.3' })
// 'https://cdn.jsdelivr.net/npm/@nanonomad/[email protected]/assets/dog/dog.css'

getCdnCharactersRoot(version?)

Returns the base CDN URL for the characters directory. Useful for constructing custom paths.

import { getCdnCharactersRoot } from '@nanonomad/characters'

getCdnCharactersRoot('1.0.3')
// 'https://cdn.jsdelivr.net/npm/@nanonomad/[email protected]/assets'

getCdnAssetsRoot(version?)

Returns the base CDN URL for the top-level assets directory.

import { getCdnAssetsRoot } from '@nanonomad/characters'

getCdnAssetsRoot('1.0.3')
// 'https://cdn.jsdelivr.net/npm/@nanonomad/[email protected]/assets'

getCharacterUrlsUnpkg(characterId, options?)

Same as getCharacterUrls but uses unpkg.com instead of jsDelivr. Use this as a fallback if jsDelivr is unavailable in your region.

import { getCharacterUrlsUnpkg } from '@nanonomad/characters'

getCharacterUrlsUnpkg('default', { version: '1.0.3' })
// {
//   character: 'default',
//   characterBaseUrl: 'https://unpkg.com/@nanonomad/[email protected]/assets/default/',
//   characterConfigUrl: 'https://unpkg.com/@nanonomad/[email protected]/assets/default/character.json'
// }

PACKAGE_VERSION

A string constant equal to the currently installed version of this package. Used internally by the helpers when no version is supplied.

import { PACKAGE_VERSION } from '@nanonomad/characters'

console.log(PACKAGE_VERSION) // '1.0.3'

The character.json format

Each character is described by a character.json file. Understanding this format is useful when building custom characters or inspecting why a character behaves a certain way.

{
  "id": "dog",
  "name": "Doggo",
  "version": "1.0.3",
  "size": 48,
  "capabilities": ["idle", "walk", "run", "jump", "sit", "sleep", "pee", "fall"],
  "poses": {
    "front": "dog-front.svg",
    "side":  "dog-side.svg",
    "sleep": "dog-sleep.svg",
    "pee":   "dog-pee.svg",
    "jump":  "dog-jump.svg"
  },
  "statePoses": {
    "idle":  "front",
    "sit":   "front",
    "walk":  "side",
    "run":   "side",
    "sleep": "sleep",
    "pee":   "pee",
    "jump":  "jump",
    "fall":  "jump"
  },
  "colorPalette": {
    "body":   { "label": "Body",    "default": "#D4943A" },
    "belly":  { "label": "Belly",   "default": "#F0D090" },
    "ears":   { "label": "Ears",    "default": "#8B5E2B" },
    "detail": { "label": "Details", "default": "#2D2D2D" },
    "eyes":   { "label": "Eyes",    "default": "#FFFFFF" },
    "tongue": { "label": "Tongue",  "default": "#FF6B8A" }
  },
  "limits": {
    "gravity":   900,
    "walkSpeed": 80,
    "walkAccel": 450,
    "jumpForce": 350,
    "friction":  8
  },
  "states": {
    "idle":  { "minDuration": 2000, "maxDuration": 4000 },
    "walk":  { "minDuration": 2000, "maxDuration": 5000 },
    "run":   { "minDuration": 1500, "maxDuration": 3000 },
    "sleep": { "minDuration": 5000, "maxDuration": 10000 }
  },
  "transitions": {
    "idle":  { "walk": 25, "run": 20, "jump": 10, "sit": 15, "sleep": 15, "pee": 10, "idle": 5 },
    "walk":  { "idle": 30, "run": 20, "jump": 10, "sit": 10, "pee": 10, "walk": 20 },
    "sit":   { "idle": 40, "walk": 25, "sleep": 20, "jump": 15 }
  }
}

| Field | Description | |---|---| | id | Must match the character folder name in this package (e.g. assets/default/, assets/dog/). | | size | The pet's rendered size in CSS pixels. | | capabilities | List of behavior states this character supports. Must correspond to registered engine capabilities. | | poses | Maps pose names to SVG filenames within the character's folder. | | statePoses | Maps each behavior state to the pose name that should be displayed. | | colorPalette | Declares the color keys and default values. Keys here can be overridden via customColors in the engine config. | | limits | Physics constants: gravity (px/s²), walkSpeed (px/s), walkAccel (px/s²), jumpForce (px/s), friction (multiplier). | | states | Per-state duration ranges in milliseconds. minDuration and maxDuration define the random window a state will remain active. | | transitions | Weighted probability table. Keys are the current state; values map each possible next state to a relative weight. Higher weight means that state is chosen more often. |

Asset file structure reference

assets/
  pet.css                          # Base overlay and container styles (always load this)
  registry.json                    # Index of available characters
  default/
    character.json                 # Character definition
    default.css                    # Color variable stylesheet
    default-front.svg              # Idle and sit pose
    default-side.svg               # Walk pose
    default-sit.svg                # Sit pose
    default-fall.svg               # Fall and jump pose
  dog/
    character.json
    dog.css
    dog-front.svg                  # Idle and sit pose
    dog-side.svg                   # Walk and run pose
    dog-jump.svg                   # Jump and fall pose
    dog-sleep.svg                  # Sleep pose
    dog-pee.svg                    # Pee pose

License

GPL-2.0-or-later