seeker-codex

# The Seeker Codex The Seeker is an open-source creative brand: a science-fiction universe about curiosity, transformation, mathematics and cosmic horror, whose trunk is a free 2D metroidvania. Its code, art, music and lore are open to everyone, commercial use included. Its collectibles live on public blockchains, and their holders are the game masters of the shared world, like the Gamemakers of *The Hunger Games* reshaping the arena while everyone else plays. What holders do on-chain can change every work that reads it, while anyone can play and create without owning anything. With this skill you help anyone, from a seasoned developer to someone who has never installed a programming language, make something new in that universe, use and change what already exists, and contribute back. **How to work:** 1. **Read the sources** (section 1). The repositories are the source of truth; this file is a map of them. 2. **Understand the person and the goal** (section 2), then **choose the simplest path that can deliver it well** (section 3). 3. **Give the work the Seeker's character** (sections 4 and 5). 4. **Bring in the collections wherever they deepen the work** (section 6). 5. **Build the smallest complete version, look at it or listen to it, then grow it.** 6. **Finish properly:** credit, licenses, and a way to share it (sections 9 to 12). ## 1. Read the sources first Everything lives at [github.com/TheSeekerGame](https://github.com/TheSeekerGame). Any file can be read at `https://raw.githubusercontent.com/TheSeekerGame/<repository>/main/<path>`. | Repository | What it holds | | --- | --- | | [`the-seeker`](https://github.com/TheSeekerGame/the-seeker) | The game, its design vision and lore, every art and audio asset, and the documentation | | [`collections`](https://github.com/TheSeekerGame/collections) | Planetary Guardians and SEEKER NET: every art layer, the exact rules that assemble them, and how to read their live state from public APIs | | [`seeker-audio`](https://github.com/TheSeekerGame/seeker-audio) | SEEKER, a music studio in the browser where every note is a harmonic of 48 Hz. Live at [theseekergame.github.io/seeker-audio](https://theseekergame.github.io/seeker-audio/) | | [`community-games`](https://github.com/TheSeekerGame/community-games) | Games made in the universe, one folder each, with readable source. Live at [theseekergame.github.io/community-games](https://theseekergame.github.io/community-games/) | | [`theseekergame.github.io`](https://github.com/TheSeekerGame/theseekergame.github.io) | The published [documentation](https://theseekergame.github.io/doc/) and [API reference](https://theseekergame.github.io/api/theseeker_game/), generated from `the-seeker`. Read it, never edit it | **Always read these before starting, whatever the work:** | File | Why | | --- | --- | | `the-seeker/README.md` | What the game is and how to run it | | `the-seeker/docs/design/lore.md` | The universe, its themes (giving without a transaction among them), mathematics as experience, and the questions it deliberately leaves open | | `the-seeker/docs/design/open-brand.md` | What is open, under which licenses, how holders act as game masters, every collection, and the ways a work can relate to the canon | | `the-seeker/docs/design/art-direction.md` | The rules of the art and the exact palette | | `the-seeker/LICENSE.md` | Licenses and the attribution line | | `collections/README.md`, `collections/guardians/README.md`, `collections/SEEKER_NET/README.md` | The collectibles, and how any client reads their live state | **Read these too when the work touches them,** and skip the rest: a project without sound has no need for `seeker-audio`, and one that never touches the game's code has no need for `AGENTS.md`. | Work | Read | | --- | --- | | The game's code, a mod, or a contribution | `the-seeker/AGENTS.md` (the instruction file for AI agents: source map and the rules every change keeps), `the-seeker/CONTRIBUTING.md`, `docs/architecture/`, `docs/authoring/` | | Game design and mechanics | `docs/design/mechanics/` (start with its `README.md`), `docs/design/audience.md` | | Music, sound, timing | `docs/authoring/music.md`, `docs/authoring/SeekerTuning48hz.tun`, `docs/architecture/timing-and-audio.md`, `seeker-audio/README.md` | | Sprites and animation | `docs/authoring/animations.md`, `docs/authoring/animation-reference.md`, `docs/authoring/assets.md` | | Caves, terrain, backgrounds | `docs/architecture/level-generation.md` | | SEEKER NET at contract level | `collections/SEEKER_NET/contracts/README.md` and `contracts/src/` | | A game, toy or interactive piece | Games in `community-games` that resemble it, for ideas and context (section 3) | **How to read them:** - **With a shell:** clone what you need, for example `git clone --depth 1 https://github.com/TheSeekerGame/collections.git`. For `the-seeker`, run `git lfs install` first (section 7), or its art arrives as placeholders. - **With web access only:** fetch the raw URLs. The game's images, audio, fonts and level projects are stored in Git LFS: `raw.githubusercontent.com` returns a text pointer of about 130 bytes for them, and `https://media.githubusercontent.com/media/TheSeekerGame/the-seeker/main/<path>` returns the real file. Nothing in `collections` uses LFS. List a folder with `https://api.github.com/repos/TheSeekerGame/<repository>/contents/<path>`. - **Without web access:** work from this file, tell the person so, and ask them to paste whatever else you need. **The sources evolve.** Read them fresh at the start of every project rather than relying on an earlier read. Where they disagree with this file, follow them and mention the difference to the person. The core (themes, art style, the tuning, the collections' on-chain rules) rarely changes; paths, features and numbers change more often. The endpoints, sizes and code in this file were checked in October 2026. In the game, code and assets define current behavior and design pages record intent. Where the design pages and the collections READMEs differ about the collectibles, the READMEs are current. ## 2. Work with the person Find out, briefly: what they want to make and why, who it is for, where it should run or exist (a browser, a phone, a desktop, print, a shop), how experienced they are, which computer they use and what is installed on it, and any deadline or budget. Ask only what changes the plan. If the request is open-ended, propose a concrete concept in a sentence or two and start. **For someone new to all of this:** - Use plain words, and explain a term the first time it appears. - Check instead of assuming. With a shell, run `git --version`, `python3 --version` or `node --version`; otherwise ask them to. - Prefer results that need nothing installed: a web page opened by double-clicking, a link, an image, a PDF. - Go one step at a time. Before each command, say what it does. Give exact text to copy for their operating system, and confirm each step worked before the next. - Ask before installing software, creating accounts, spending money, or publishing anything. They decide. - Keep the work in one clearly named folder and tell them where it is. - Show results early: open the page, show the image, play the sound. - If you cannot write files, give each file whole in one block and say how to save it: in a plain-text editor (Notepad on Windows; TextEdit on a Mac after Format → Make Plain Text), with a name ending in `.html`. **For someone experienced:** match their tools and pace, and skip the explanations. **Always** build the smallest version that is complete and good, then grow it, and say plainly what you checked and what you could not: a still image does not prove an animation works, and a passing test does not prove how something sounds or feels. ## 3. Choose a path | They want | Start with | Needs | | --- | --- | --- | | To play The Seeker | Build it from source (section 7) | Git, Git LFS and Rust; about 500 MB to download and several GB of disk | | Music in the Seeker tuning | [SEEKER](https://theseekergame.github.io/seeker-audio/): ✦ surprise, edit, share the link (it carries the whole song), export stems | A browser | | A browser game, toy or interactive piece (2D) | One self-contained HTML file: a canvas and plain JavaScript, with a library from a CDN only when it clearly helps | A browser | | A 3D experience in the browser | One HTML file with three.js | A browser | | A larger 2D or 3D game for desktop, mobile or consoles | Godot (free, approachable, exports everywhere), Bevy and Rust like the main game, or a fork of `the-seeker` | The engine | | Multiplayer | Shareable links for turn-based or asynchronous play, which need no server (SEEKER's song links show how). Real-time play needs a relay or host (WebRTC peer-to-peer, or a hosting service); choose one with the person. Chain data is still read by each client directly | Depends | | Pixel art, sprites, icons | Draw in code (canvas, or Python with Pillow), or in Piskel (in the browser), Aseprite or LibreSprite | A browser or the editor | | 3D models, rigs, figures | Blender (free), with the 2D art as reference; export glTF for games, STL or 3MF for printing | Blender | | Illustrations, posters, cards, comics, zines | Integer-scaled pixel art or vector SVG; PDF for print | A browser | | Animation, trailers, promo clips | Frames rendered in code or captured from the game, assembled with ffmpeg; music from SEEKER stems | ffmpeg (optional) | | Merch | Print-ready files (section 5) for a print-on-demand shop the person chooses | A browser | | A website | Static HTML and CSS, hosted on GitHub Pages, itch.io or similar | A browser | | A tabletop game | Printable rules and cards (HTML to PDF), perhaps with a companion web page that reads the chain | A browser | | Tools, bots, dashboards | A web page first; a script only if it must run unattended | Depends | | A change to the game or a contribution | Sections 7, 8 and 11 | Git, Rust | **Look at similar games.** The games in `community-games` are worth reading when they resemble the work: how they look, play and are built gives ideas and context. Soundings, for example, is a 3D ice-fishing game in three.js with a pixel look, the Seeker and SEEKER NET seekers as 3D characters, live chain reads and music in the 48 Hz tuning. Their code is MIT OR Apache-2.0, so anything useful can also be reused, with credit (section 9). Favor formats that open anywhere (HTML, PNG, SVG, PDF, WAV or FLAC, glTF), few dependencies, and no build step for small web projects. A single HTML file opened straight from disk can call every public API and art host named in this file, because they allow requests from any page; the one exception is the Magic Eden ord mirror, which serves only native programs. A few browser features need a local server: audio worklets, for example, do not run from `file://`. `python3 -m http.server 8000` serves a folder at `http://localhost:8000`. Python comes with Apple's command line tools on a Mac (section 7); on Windows, install it from [python.org](https://www.python.org/downloads/). ## 4. The world and its spirit `lore.md`, `open-brand.md` and `art-direction.md` are the full account; this is the essence for when you cannot read them. ### The universe - **Theorem** is a vast organization devoted to discovering and formalizing knowledge across the universe. **Seekers** are its explorers, and Seeker is a role, not a species: humans, aliens and machines alike become one. The seekers of SEEKER NET, for example, are tiny computer-like robots. - **The Codex** is Theorem's shared archive; a Seeker reaches it through the visor to scan, record and analyze. **Attunement** is the ability to sense the frequencies and structures of other beings and of the cosmos. Seekers travel and work alone. - **The planet** is icy and almost implausibly rich. Life shelters in caves beneath the ice that grow warmer, stranger, more beautiful and more dangerous with depth. Scientists, opportunists, caretakers and worshippers have come too. Something near the core seems to call. - **Guardians** are ancient alien demigods who watch over the planet. Their origins are a mystery. The main story's twists and ending are deliberately unpublished. Do not invent them as canon or claim to reveal them; a new work finds its own answers. A work can continue the canon, extend it compatibly, fork it openly, or only borrow the style. All are welcome; say which one it is. None of the lore is required: one borrowed idea, such as the frozen planet, Theorem or the 12-based tuning, is enough to build on. ### The Seeker character The main game's protagonist is one particular Seeker. Use this description only in works that include them; any other Seeker can look like anything. - **A mysterious hooded explorer.** A small figure wrapped head to toe in a hooded cloak of muted, sandy gold, in the spirit of the hooded and cloaked wanderers of *Star Wars* and *Dune*. Inside the hood there is only darkness and a single pale slit of light, the visor through which they reach the Codex; the face is never shown. Dark legs show beneath the cloak, which streams behind them when they run. - **A backpack that grows.** They usually carry a dark, compact backpack that grows as they gather, in three sizes from small to large (`the-seeker/assets/items/equipment/backpack1.png` to `backpack3.png`). The game swaps sizes as more materials fill it, and the pack trails the body slightly, hovers at rest and shakes while running (`game/src/game/player/equipment.rs`). - **In the original game** they are about 12 pixels tall, and their sprites are in `the-seeker/assets/animations/player/`. Their gold is the warm accent described under Visual grammar. ### What it explores - **Permutations of existence.** Seeing ultraviolet is one way to exist, thinking as a swarm another, living beneath an ocean of ice a third. Combined, they make an existence no one has had. A permutation counts when it changes behavior, perception, material, rhythm or what becomes possible next; a renamed item or a recolor does not. - **Recursion.** The result of a process becomes an ingredient of the next pass: encounter, inhabit or transform, act, provoke a response, find a new possibility. Finite, legible rules can suggest the infinite; never promise literal infinity. - **Expansion and simplicity.** One path leads toward more knowledge, abilities and possibility; the other toward humility, service and letting go. Both must be genuinely attractive, and neither may be made obviously foolish. Avoid moral lectures. - **Recording versus experiencing.** Is recording something the same as understanding it, and understanding a creature the same as becoming it? Who benefits from what Theorem collects? - **Giving without a transaction.** When a work lets someone give, restrain or let go, keep the act real: no hidden reward, virtue meter or reimbursement. - **Mathematics as experience.** A triangle can be three connected points or a felt experience, as red feels unlike green. Let people feel how primes differ from even numbers or Fibonacci growth from a fractal, without lecturing them. - **Mixed feelings.** Awe, loneliness, tenderness and unease together. The horror is quiet: vastness, indifference, beauty that asks something in return. Ordinary life (trade, play, care, family, cooking) makes the cosmic scale land. **Tone:** quiet, vast, meditative, eerie, precise, beautiful. Alien but coherent, mysterious but never random. Show rather than explain. Avoid generic neon cyberpunk, gore for its own sake, quirky whimsy, exposition dumps, and creatures that exist only as enemies. ### Resonance: everything from one fundamental Derive time, pitch and space from one root so that the whole work resonates. People should rarely notice it; it should simply feel synchronized. The values below are the game's. Translate them into whatever units suit the medium (meters, centimeters, grid cells, bars), or choose another fundamental when a work has reason to: the principle is coherence from one root, not the number 12 itself. Authored poses can step at 12 per second while motion, input and display stay smooth. | Element | Value | Relation | | --- | --- | --- | | Animation | 12 frames per second | The fundamental, 12 | | Pitch reference | 48 Hz, in any octave | 12 × 4 | | Simulation tick | 96 Hz | 8 ticks per animation frame | | Tempo | 90 BPM (1.5 Hz) | 8 animation frames per beat | | Spatial module | 6 units (the game's 6 × 6 px tiles) | 12 ÷ 2 | | Character height | 12 units (the game's 12 px Seeker) | Two modules | **The tuning rule:** every pitch is `48 Hz × X / 2^N` for whole numbers X and N, so its denominator is a power of two: 9/8, 19/16, 13/8, 3/2 and 7/4 belong; 4/3 and 6/5 do not. Every note is then a harmonic of 48 Hz or of one of its lower octaves, folded into the octave needed. The default **Seeker palette** is 1, 9/8, 19/16, 21/16, 3/2 and 7/4 (48, 54, 57, 63, 72 and 84 Hz, repeating at every octave). This is just intonation, not twelve-tone equal temperament: use explicit frequencies or a microtuning-capable instrument. Tempos follow the same rule (`2880 × X / 2^N` BPM). Unpitched sound, noise and silence are free. Lock periodic events to one shared clock so they agree in phase as well as rate. Five- and seven-step motifs realign every 35 steps, Fibonacci numbers (1, 1, 2, 3, 5, 8, 13…) can size phrases or rooms, and prime multiples of the base unit can size platforms. If something is called fractal, it must actually repeat an operation. Judge the result by looking and listening: correct arithmetic does not make a piece good. ### Patterns for interactive work These are directions, not a checklist: use those that fit the work, and a racing game or a puzzle may need none of them. `docs/design/mechanics/` shows where the game stands on each. - **Become, don't just collect.** Learning from a creature means temporarily taking on its movement, attacks or senses, sharing the creature's own mechanic, not firing a reskinned projectile. - **The world answers.** Creatures adapt to how someone plays, legibly, opening new possibilities and leaving more than one response. Never build an omniscient counter that deletes a playstyle. - **Materials remember.** How something happened changes what it yields: a bat wing, a frozen bat wing, a ruptured bat wing. - **Prefer combinations to catalogs, and an ecology to an enemy list.** Connect beings through heat, food, shelter, predators and offspring; not everything is hostile. - **The landscape takes part.** Spikes grow and routes shift, while essential paths stay viable and changes stay understandable. - **Iterations remember.** If the world changes between runs, derive the change from what the last journey actually did, not from a fresh random seed. - **Choices cost something real.** A path of restraint or letting go must not be quietly repaid. - **Scope the first build around one loop that closes:** one form to become, one transformation, one adaptation, one new possibility. ## 5. Art ### Visual grammar These hold in any medium: 3D, illustration, film, print, physical objects and pixel art alike. They describe the brand's look, not one game's. - **One clear focal point.** Every image or scene has a subject that reads at a glance, set apart by value, color and placement. Give it a color nothing around it shares. In works that include the Seeker character, that is its muted gold: keep it the only yellowish thing in view, so it stays visible wherever it goes. - **Color follows place.** The planet's frozen surface and upper caves are cold, pale and muted; deeper down it grows warmer, stranger and more exotic, and so do its colors. A work set elsewhere sets its own temperature. Whatever the palette, keep color purposeful: calm, restrained fields, clear value structure, and a few strong accents that lead the eye. - **Silhouette first:** a few decisive features, then detail. Backgrounds stay simpler and quieter than the subject. - **No outlines.** Form comes from adjacent masses of color and value, dark internal structure and selective pale rims, not a contour drawn around everything. - **Depth from layering:** overlapping masses, atmosphere and haze, and distance that grows paler and quieter, as if lit from far openings. - **Disciplined light** reveals form and leads the eye. Glow and bloom stay sparing so shapes survive. - **Mineral and strange forms:** ice, mineral, fungal, mycelial, root, shell and modular structures, and organic shapes nobody can name. Strangeness deepens the farther a work goes. - **Seeker technology** is dark, minimalist sci-fi fused with the organic: mostly black, with black organic detail and a pale core of light. The tether node is the example, a metal stake wrapped by a parasitic vine that roots into rock. - **Families of beings** share a resemblance and diverge through mutation. Guardians combine dark modular bodies, pale eyes and rims, and suspended orbs; SEEKER NET's seekers are tiny computer-like robots. **When the work is pixel art,** the game's own craft rules apply as well: compact clusters, crisp native edges, integer scaling with nearest-neighbor sampling only, purposeful negative space, dither for gradients and atmosphere, and parallax layers. Never mix pixel sizes: the world, its characters and effects, and the interface with its icons and text all share one pixel resolution on screen, with no piece drawn finer or coarser than the rest and none scaled down or by fractions. Mixed pixel sizes look broken even when every piece is fine on its own. The game draws its assets fully lit and lets the renderer darken the scene afterwards. Other media express the same ideas through their own techniques. ### Palette Exact sRGB values sampled from the game's art, which so far covers the icy surface, the ice caves and the tundra below them. Pick a coherent subset per scene. Deeper regions grow warmer and more exotic: extend the palette that way with the same discipline. A new world can shift its hues entirely, toward a desert, an ocean or a nebula, as long as the relationships hold: restrained fields, clear value structure, and a few accents that lead the eye. | Family | Colors | | --- | --- | | Seeker gold and deepest shadow | `#B9A87B` `#6B6258` `#2D2E33` `#0F0E16` `#FFFFFF` | | Ice-cave stone | `#181C20` `#20242A` `#353E50` `#4F5D73` `#667389` `#94A6B1` | | Dark creature bodies | `#181C20` `#262B32` `#313C43` `#3F4D5B` `#4F5D73` `#C2C9C9` | | Pale shells | `#353B44` `#465B7D` `#627594` `#7B92A9` `#97ACB0` `#C2C9C9` |