# Zoark

> Zoark (https://zoark.org) is an open library of animated 3D creatures, real and invented.
> Each one is rebuilt from a skeleton and published as a glTF 2.0 binary, skeleton.glb (every
> bone), with its skeleton and spec as JSON. Every specimen has a stable ARK id. Reading is free: no account,
> no API key, CORS open.

Same content as a page: https://zoark.org/opensource/

## Answers in one line

- What is Zoark? An open library of animated 3D creatures rebuilt from skeletons, as .glb files.
- Is reading free? Yes. The read endpoints below need no account and no key; CORS is open.
- Can an AI agent create a creature? Not yet. People create on the website (describe -> edit
  the draft -> GEN), with daily limits. There is no public creation API.
- How is a specimen identified? ARK id, e.g. ARK-MAM-0001. It never changes and never points
  to a different creature.
- Licence? Not announced yet, for the specimen files or the source code. This file will state
  it as soon as it is decided.

## Entry points

- GET https://zoark.org/api/specimens?page=1&q=fox
  List or search, newest first, 12 per page. Returns {items[], page, has_more}.
- GET https://zoark.org/api/specimens/{id}
  One specimen: spec, description, lineage, remixes, build stages.
- GET https://zoark.org/api/files/specimens/{id}/v1/skeleton.glb
  The 3D model: every bone. spec.json and skeleton.json sit at the same path. Add ?download=1.
- GET https://zoark.org/api/schema
  JSON Schema of spec.json.
- https://zoark.org/sitemap.xml   every page, including each specimen.
- https://zoark.org/specimen/{id} the page for people.

List item fields: id, name, sci_name, kind (invented|real), taxon_code, body_plan,
size_m (head-body length in metres, tail excluded), parent_id, root_id, source (create|remix),
created_at (ms since epoch), glb_url (skeleton.glb).

## GLB format

- glTF 2.0 binary, 0 errors in the Khronos glTF Validator.
- Y up, metres, facing +Z, feet on Y = 0, centred.
- One skin; root bone named "root"; rest rotations are identity.
- Named clips, 30 fps, looping: "idle" always; "walk" and "run" when the creature moves that
  way. Movements the engine cannot animate yet are listed as "not animated yet".
- Under 2 MB. The same spec and id always produce the same file, byte for byte.

## spec.json

Required: schema_version, source, species, prompt (the user's own words), description (the full
description), taxon_code, body_plan, limbs, size_m. Optional: taxon (closest real animal,
lineage, gait), tail, proportions, features, locomotion.
body_plan: quadruped, biped, hexapod, octopod, serpentine, fish, avian. The engine builds
quadrupeds today; the others are refused with a clear message until supported.

## skeleton.json

Bones, spine order, limb joint chains and joint positions, in metres; each measured number is
tagged with where it came from. Still changing while the skeleton research continues; rely on
spec.json instead.

## Ids and remixes

- ARK-{taxon}-{number}. Taxon codes: MAM mammal, AVE bird, REP reptile, AMP amphibian,
  PIS fish, ART arthropod, MOL mollusc, OTH other.
- Remix: {original id}.r{n}, e.g. ARK-MAM-0001.r2. parent_id = direct parent,
  root_id = the original. A remix changes numbers, never the original.

## How to cite

Zoark specimen ARK-MAM-0001. https://zoark.org/specimen/ARK-MAM-0001

## Not done yet

The skeleton and animation steps still run placeholder implementations; each
specimen's "stages" field says which. The source code repository is not public yet.