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, notlocalStorageorsessionStorage. 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.
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" }
} | field | accepted values | purpose |
|---|---|---|
entry | relative HTML path | Use a generated entry outside the root, which Prototir copies to the served root. |
thumbnail | auto, or a bundle-relative image path | auto 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. |
modules | available exact name@version specs | Injects the validated import map. Unknown or planned modules are rejected. |
permissions | camera, microphone | Lets the player ask the visitor before granting device access. |
devices | desktop, mobile, both | Sets visitor expectations without blocking other devices. |
orientation | any, portrait, landscape | Shows the intended viewport orientation. |
ai | disabled, managed | Enables 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'); | Member | Kind | What it can do |
|---|---|---|
ready() | function | Starts a real session after the prototype becomes interactive. |
event(name, data?) | function | Records a small, non-personal milestone for analytics. |
score(value) | function | Reports the current numeric score. |
storage | member | Contains asynchronous get, set, and remove functions
for prototype-scoped strings. |
ai | member | Contains provider-neutral generate. It is available only when
managed AI is enabled. |
rng(seed?) | function | Returns 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
}); promptis required and limited to 32,000 characters.maxTokensis optional, must be positive, and is capped at 4,096 output tokens or the remaining allowance.- The call rejects with
{ code, message }. Handlesign_in_required,quota_exceeded,team_fair_share_exceeded,prototype_allowance_exceeded,ai_rate_limited,ai_blocked, moderation errors,provider_error, andtimeout. - 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.
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.
08 / Publish
Run the release checklist
- 1. Build locally. Open the production output through a local static server, not directly from the filesystem.
- 2. Test the sandbox assumptions. Remove arbitrary network dependencies, externalize scripts, and test without hidden environment variables.
- 3. ZIP the output contents. Check the archive root, compressed size, entry file, relative assets, manifest, and license files.
- 4. Complete the public page. Choose the publishing identity, category, tags, description, lineage, and rights confirmation.
- 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. 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.
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.
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.