Creator documentation

Build something people can actually try.

A practical guide to the bundle, sandbox, SDK, publishing choices, reusable building blocks, and event tools behind every Prototir prototype.

Static bundle

HTML, CSS, JS, and assets

Small SDK

Sessions, events, and scores

Reusable starts

Modules and full templates

Real feedback

Sessions, comments, and events

01 / Prototype

What Prototir runs

A prototype is a client-side web experience that opens inside a contained player. It can be a game, tool, app concept, interactive artwork, product flow, simulation, or any other idea that benefits from being used instead of merely described.

Good prototype scope

One important behavior, a clear first action, and enough finish that a stranger can test it without the creator standing beside them.

Not required

A production backend, an app-store package, a finished product, or a complete feature set. Prototir is for learning before all of that is built.

02 / Bundle

Package a browser-ready ZIP

Upload the built files a browser needs, not your source repository or development server. Put index.html at the ZIP root, or declare another HTML entry in a root-level prototir.json. Use relative paths so every asset stays inside the bundle.

my-prototype/
|-- index.html
|-- app.js
|-- styles.css
|-- assets/
|   |-- cover.webp
|   `-- model.glb
`-- prototir.json
  • Use external JavaScript files. Inline executable scripts are blocked by the sandbox.
  • Bundle fonts, images, audio, models, and data with relative URLs.
  • Do not depend on your own server, runtime package install, arbitrary fetch, sockets, or third-party API calls.
  • Use the SDK for platform features and the curated module CDN for declared dependencies.
  • Use Prototir.storage, not localStorage or sessionStorage. Prototype frames intentionally have an opaque origin.
  • Keep the compressed ZIP within your plan: Free 10 MB, Pro 25 MB, Team 50 MB, Enterprise 75 MB.
Framework projects: run the production build first, then ZIP the contents of the output folder. A Vite, React, Svelte, Vue, Phaser, or Three.js source tree is not itself a deployable prototype unless its generated browser files are included.

03 / Manifest

Describe runtime needs explicitly

The optional root-level manifest lets the upload pipeline validate and prepare the prototype. Form values remain authoritative; a manifest description and tags are used as fallbacks when the form leaves them empty.

{
  "description": "A short explanation for people trying the prototype.",
  "tags": ["Physics", "Co-op"],
  "entry": "index.html",
  "thumbnail": "auto",
  "modules": ["three@0.170.0", "prefab-input@0.2.0"],
  "permissions": [],
  "devices": "both",
  "orientation": "landscape",
  "ai": { "mode": "disabled" }
}
fieldaccepted valuespurpose
entryrelative HTML pathUse a generated entry outside the root, which Prototir copies to the served root.
thumbnailauto, or a bundle-relative image pathauto captures the first available visual frame after upload, including an intro or cutscene. A bundle-relative PNG, JPEG, or WebP travels with the ZIP and prototir.json, bypasses runtime capture, and is the deterministic choice when the representative scene appears later. Alternatively, upload a Prototir-hosted custom image (up to 2 MB); it overrides the portable source until you switch back in Studio. The last source you save wins. Use 1280×800 (16:10) where possible — cards center-crop it to 16:10 and 16:9.
modulesavailable exact name@version specsInjects the validated import map. Unknown or planned modules are rejected.
permissionscamera, microphoneLets the player ask the visitor before granting device access.
devicesdesktop, mobile, bothSets visitor expectations without blocking other devices.
orientationany, portrait, landscapeShows the intended viewport orientation.
aidisabled, managedEnables Prototir's provider-neutral managed gateway. API keys, provider names, and model ids do not belong in the manifest.

Browse exact versions, requirements, sizes, and availability in the module catalog.

04 / SDK

Tell the shell what happened

Load the SDK before your external application file. Call ready() only after the first meaningful interaction is possible. That signal begins measurement of a real session. Preview generation does not wait for ready(), so a cutscene should call it only when control reaches the visitor; choose a bundled thumbnail when the public image should show a later scene.

<script src="https://cdn.prototir.com/sdk/v0.0.1/prototir.js"></script>
<script type="module" src="./app.js"></script>
// Call this when the prototype is visible and interactive.
Prototir.ready();

// Record meaningful milestones for creator analytics.
Prototir.event('onboarding_complete', { route: 'guided' });

// Optional: update a challenge-compatible score.
Prototir.score(1200);

// Storage is scoped to this prototype in this browser.
await Prototir.storage.set('difficulty', 'hard');

// Reproducible randomness for fair runs and daily variations.
const random = Prototir.rng('daily-2026-07-23');
MemberKindWhat it can do
ready()functionStarts a real session after the prototype becomes interactive.
event(name, data?)functionRecords a small, non-personal milestone for analytics.
score(value)functionReports the current numeric score.
storagememberContains asynchronous get, set, and remove functions for prototype-scoped strings.
aimemberContains provider-neutral generate. It is available only when managed AI is enabled.
rng(seed?)functionReturns a deterministic local random-number function.

Managed AI

Managed AI is a Pro-and-above feature, and it runs on your plan's daily allowance, never a visitor's. Creators and players do not supply provider keys or pick a vendor. Prototir selects the provider and model behind the tier you choose, automatically falling back to another provider if one is briefly unavailable, scans prompts and replies, and shows an AI-powered disclosure in the player shell. Prompt text leaves the device.

// Enable with: "ai": { "mode": "managed" } in prototir.json.
// Calls are stateless, so include any conversation history you need.
const answer = await Prototir.ai.generate({
  prompt: 'Reply as a concise museum guide: What is chiaroscuro?',
  maxTokens: 160
});
  • prompt is required and limited to 32,000 characters.
  • maxTokens is optional, must be positive, and is capped at 4,096 output tokens or the remaining allowance.
  • The call rejects with { code, message }. Handle sign_in_required, quota_exceeded, team_fair_share_exceeded, prototype_allowance_exceeded, ai_rate_limited, ai_blocked, moderation errors, provider_error, and timeout.
  • Calls are stateless. Prototir does not maintain a conversation, tools, retrieval, or long-term memory for the prototype.
  • Browser-local inference is not part of this capability yet. Use managed AI for consistent device support.

The rest is configured on the prototype's own page, not in code, under "AI (Prototir.ai)": mode, model tier (fast, cheap and low-latency, or quality, higher-capability and costlier), whether a visitor must sign in to use it, and an optional daily token cap per visitor on top of your own budget. Defaults (managed off, fast tier, sign-in required, your full daily budget per visitor) are chosen to be safe and cheap out of the box. Turning off sign-in lets anonymous visitors use AI too, metered per visitor by IP instead of by account. You still pay either way; there's just no account to individually rate-limit, so it's a frictionless-demo versus coarser-abuse-protection trade.

Fast and Quality each have their own included daily allowance, sized for what they actually cost to run, not one shared number. Once a day's allowance for the tier you're using is spent, AI keeps working out of any purchased AI credits (one-time top-ups you buy from the same panel). Once both are spent, managed AI pauses until the next daily reset, or more credits. A Team org's daily allowances and credits are shared across every prototype the org owns.

Useful events

First action, onboarding completion, important tool use, level completion, creation/export, retry, and a clearly named abandonment point.

Keep telemetry safe

Use stable short names and small values. Never place names, email addresses, free-form messages, secrets, or other personal data in event payloads.

05 / Quality

Design for an unfamiliar visitor

First ten seconds

Show what can be touched, clicked, typed, dragged, or controlled. Avoid an unexplained blank canvas.

Viewport

Fill the available frame, handle resize, avoid fixed desktop-only dimensions, and honor the declared orientation.

Input

Test keyboard, pointer, touch, focus order, and visible controls. Use prefab-input when one interaction must work on desktop and mobile.

Recovery

Give visitors a restart path, useful empty states, and a clear response when an optional permission or AI request is denied.

Performance

Compress assets, lazy-load secondary content, cap pixel density, and test the first load on a real phone and ordinary connection.

Accessibility

Use readable contrast, semantic controls, labels, keyboard access, reduced-motion handling, and alternatives to audio-only or color-only information.

06 / Page setup

Help the right people understand it

  • Title: identify the idea, not its internal build number.
  • Category: choose game, app, art, or showcase as the broad format.
  • Prototype tags: add up to five descriptors for mechanics, audience, technology, or subject. Existing normalized tags are reused despite case, spacing, or underscore differences.
  • Description: explain what to try, what is unfinished, intended device/input, and the question you need answered. Links open through Prototir's external-site warning.
  • Feedback tags: these are separate from prototype tags. They structure what commenters observed, such as confusing, delightful, slow, or would-use.
A useful description: “Try creating a two-stop route on mobile. The map is mock data. I want to learn whether the order controls are understandable without a tutorial.”

07 / Source

Make reuse traceable

Only publish files you own or are allowed to distribute. Keep third-party license and attribution files in the bundle. If you enable source download, choose a license that actually grants the permissions you intend.

Open source

Visitors can download the source under your stated license. Platform-generated provenance is added to the downloaded manifest.

Remix

Declare the source slug or re-upload a Prototir download. The origin remains linked and conflicting lineage is rejected.

Template

A template is a complete open-source starter prototype. Its downloads carry template provenance into later uploads.

Explore templates

08 / Publish

Run the release checklist

  1. 1. Build locally. Open the production output through a local static server, not directly from the filesystem.
  2. 2. Test the sandbox assumptions. Remove arbitrary network dependencies, externalize scripts, and test without hidden environment variables.
  3. 3. ZIP the output contents. Check the archive root, compressed size, entry file, relative assets, manifest, and license files.
  4. 4. Complete the public page. Choose the publishing identity, category, tags, description, lineage, and rights confirmation.
  5. 5. Set publication behavior. Review visibility, comments, tips, source downloads/templates, embed access and domains, badge visibility, build protection, and optional release details before submitting.
  6. 6. Verify after processing. Prototir runs the candidate in the same opaque-origin sandbox and keeps it unlisted if startup throws an uncaught error. A failed Studio row opens a prefilled repair editor on the same prototype: it identifies the failed check with a stable diagnostic code, explains what to change, and lets you edit metadata, upload a replacement ZIP, or delete the prototype. New manifest values are shown as highlighted changes before the replacement is queued. Runtime-failing builds remain available to their owner and collaborators for testing while forced unlisted. After a build passes, try the player on desktop and mobile and check permissions and analytics events.
Open the publisher

09 / Events

Use a jam or challenge for a focused question

Jam

A creation event with prototype entries. It can run online, in person, or as a hybrid, with a public venue and an optional HTTPS participation link where appropriate.

  • Choose visibility independently: public is listed, unlisted works by link, and private is visible only to invited accounts and entrants.
  • Choose admission independently: open entry, host approval after an application, or invitation only. Private jams always require invitations.
  • Accept an existing live prototype or a new upload.
  • Set the submission window, optional separate voting window, bundle limit, and winner method: community, invited jury, or host selection.
  • The judged version is captured at submission time.
  • A user-hosted merit prize needs a named provider and official rules. The host handles eligibility, legal compliance, judging, delivery, taxes, and disputes.
Browse jams

Challenge

A score race on one of the host's live prototypes. The prototype reports scores through the SDK and real sessions form the leaderboard.

  • Public challenges require a real-use history.
  • Choose a general, creator-regular, or category-expert participation gate.
  • Private challenges remove the experience wall and admit named participants.
  • Use seeded randomness when every run should be comparable.
Browse challenges
Before hosting: write one clear prompt, define who may enter, give enough time to build and test, state the judging method, publish conduct and eligibility rules, and explain how results are announced. For a physical event, publish only a suitable public venue. For prizes, read the event terms and obtain legal advice where needed. Creating either event currently requires Pro or higher.
Host an event