Your world, one portal away.

Developer guide

Three steps. Most worlds are done in ten minutes.

1. Prove you own the site

After you add your world you get a token. Serve it at https://your-site/.well-known/aeonis.json:

{"token":"aeonis-verify-…"}

Or, if you can’t serve files at the root of your domain (for example a GitHub Pages project), add this tag to your world page:

<meta name="aeonis-verification" content="aeonis-verify-…">

2. Paste the snippet

This is the whole integration, and it is the same for every kind of world. No setup and no style settings: read() verifies the pass in the browser (Ed25519, checked against /.well-known/jwks.json, made for your site, not expired) and removes it from the address bar. adapt() looks at how your page draws and returns the visitor in that form.

<script type="module">
  const aeonis = await import('https://search.aeonis.pro/sdk/1.1.0/aeonis-passport.js').catch(() => null);
  const visitor = aeonis ? await aeonis.read() : { guest: true, name: 'Guest' };
  // … start your world as usual, then:
  const look = aeonis ? await aeonis.adapt(visitor) : null;
  // look.kind is '3d', 'pixel', 'vector', 'dom' or 'core'
</script>

Load the SDK before you create your canvas or scene, and call adapt() once your world is on screen. What it looks at:

Every look also carries identity (name, colours, seed, stamp count), glyph (a small badge) and detected (what the SDK found). The seed comes only from the name and colours, so the same passport looks like the same person in every world.

3. Draw the visitor

three.js

import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
if (look?.kind === '3d') {
  const gltf = await new GLTFLoader().loadAsync(look.glb);
  look.apply(gltf.scene);                       // your materials, your scale, feet at y = 0
  scene.add(gltf.scene);
  const mixer = new THREE.AnimationMixer(gltf.scene);
  mixer.clipAction(gltf.animations.find(a => a.name === 'idle')).play();   // also: walk, jog, talk, sit …
}

2D canvas (the same code works for pixel art and smooth art)

function drawVisitor(ctx, x, y, dir, frame) {   // x, y = feet, in canvas pixels
  if (look?.kind === 'pixel') look.draw(ctx, x, y, dir, frame);        // dir: 'down' | 'left' | 'right' | 'up', frame: 0–3
  else if (look?.kind === 'vector') look.draw(ctx, x, y, look.height, dir === 'left' ? -1 : 1);
  else drawYourOwnGuest(ctx, x, y);                                    // your world keeps working without Aeonis
}

Anything else

const { name, colors, seed } = look.identity;    // build the visitor from these in your own engine
badge.src = look.glyph.url;                       // or show their badge
document.querySelector('#home').href = visitor.returnUrl;   // and always offer a way back to Aeonis

Optional overrides exist if you want them: adapt(visitor, { style, target, tile, scale, palette, height }). Most worlds never need them. Version 1.0.0 of the SDK keeps working unchanged.

What the pass contains

Under the hood the pass is a JWT signed with Ed25519 (alg: EdDSA), iss https://search.aeonis.pro, aud your world’s origin, valid for 5 minutes. Browsers without Ed25519 support fall back to a check at /api/passport/verify. You can also copy the SDK file into your own project.