Creator guide

Build a browser app, upload its ready-to-run files, and publish a complete listing. Use Studio or an authorized AI connection. Hackemist hosts static HTML, CSS, JavaScript, WebAssembly and media. Build tools and backend servers run outside Hackemist.

Start with a browser-ready build

Include an index.html entry point and the assets it needs. Upload HTML, a ZIP, a build folder, or paste HTML in Studio. The importer can find a browser build inside a larger project and ignore development-only files. Review the selected entry point and preview the result. A folder containing a link or source code alone is not a runnable build: export its browser files first. Never include .env files, API secrets, passwords, private keys or server credentials.

Use relative asset paths and avoid assumptions about the site's root URL. Compile React, Vue, Godot, Unity or other engines into their supported web export before uploading. Source projects requiring npm, Python, a database or a build step are not executed on the hosting server. Check the current upload limits in Studio; the administrator controls file sizes, bundle size, file count and account storage. Large assets should fit those limits and load progressively.

Saving progress

Progress in a JavaScript variable disappears when the app closes unless your code captures and restores it. Enabling a platform option cannot discover all of that state. The player warns when account-save support is missing or unconfirmed. A save-format declaration describes your data; it does not implement saving.

For reliable account saves, use Hackemist.createProgressSaver with capture and restore callbacks. Capture a small, plain JSON snapshot of the real game state. Restore that snapshot before enabling gameplay. Handle null as a new game. Include the level, score, seed, inventory and any board state needed to reproduce progress. Do not save DOM nodes, functions, WebGL resources, arbitrary class instances or secrets.

let state = { level: 1, score: 0 };
const saver = Hackemist.createProgressSaver({
  capture: () => ({ ...state }),
  restore: saved => {
    state = saved ?? { level: 1, score: 0 };
    render();
  },
  onError: error => showSaveError(error.message)
});
await saver.ready;
enableGameplay();
// After a meaningful change:
state.score += 10;
saver.changed();

Keep progress snapshots within 64 KiB. The helper polls, debounces and serializes changes, and only reports a saved snapshot after the server acknowledges it. Await saver.flush() at checkpoints where practical. Offline play, a sudden browser crash or closing before an acknowledgement can lose the latest unsaved changes. A save failure pauses the helper; show a retry action that calls saver.reload() and restores confirmed state. Never silently overwrite a conflict with an old snapshot.

Alternatively, use Hackemist.loadProgress and Hackemist.saveProgress yourself and implement initialization, errors, checkpoints and concurrency handling. Studio's Cloud saves tab inspects bounded source hints and helps you inspect your declaration. Test a fresh account, refresh, close and reopen, a second device, and named save slots. Source hints alone do not prove that every aspect of progress is saved.

If your app already stores progress in localStorage or browser cookies, enable automatic browser-data sync under App details → Browser compatibility. This requires an isolated origin. Only supported browser data is synced, up to 5 MiB. It does not capture in-memory variables, sessionStorage, IndexedDB, a third-party frame's data or your external backend. IndexedDB can persist in that browser but needs your own integration for account recovery and synchronization. Cookies must contain app state rather than credentials.

Guests do not have Hackemist account saves. Let them play where appropriate and explain your own browser-only persistence. Do not display “saved” before an acknowledgement. Save slots, history, recovery, import/export and migration are available through the player's Saves button and the SDK. Changing slots requires reopening the app to restore the correct slot. Add hackemist-save.json with a version and supported JSON schema when your format needs validation or migration. Preserve older formats or provide an explicit migration rather than discarding players' data.

Touch, keyboard and sound

Design canvas, WebGL and DOM layouts for small screens using the available viewport, appropriate scaling and responsive UI. Allow native pointer and touch interaction in the app. Use pointer events for mouse, pen and touch, track distinct pointer IDs, and release gestures on pointercancel. Apply touch-action: none only to interactive game surfaces that require it; keep forms and page navigation usable. Respect orientation changes, safe areas and reduced-motion preferences.

Configure the optional platform controls from Studio's Player controls panel. Choose a directional/action preset, edit the labels and key mappings, and preview them on a phone. In the player, Controls opens independent Game, Keyboard and Customize toggles. Players can add up to 16 extra buttons or joysticks, name their actions, select allowed keyboard keys, remove controls locally, and drag or resize each control. Buttons can be 40–120 pixels and joysticks 64–200 pixels. Players can adjust opacity and move or resize the virtual keyboard. Hide closes the controls menu while enabled controls and the keyboard remain visible; closing Customize also keeps them available. Players switch Game or Keyboard off to hide that panel. Custom layouts and sound preferences stay on that device for that account, separate from account game saves and your project's published controls configuration.

An eight-direction joystick maps Up, Down, Left and Right to four existing keyboard actions, with diagonals holding two directions together. For analog movement, integrate the optional hackemist:input detail {type: 'joystick', controlId, axes: {x, y}, source: 'touch'} with your engine. Axes are bounded from -1 to 1 and return to zero when the stick or session is released. Player-added joysticks are local preferences; the creator/MCP configuration remains a typed button mapping.

In Customize, choose Arrange controls to uncover the play area while keeping drag and resize enabled. Hide closes only the selection menu. Reopen Controls and choose Edit mappings to return to the editor.

Map buttons to keys your app already handles. The platform generates untrusted keydown/keyup events for standard keyboard handlers and a typed hackemist:input event for direct integration. Many apps can use their existing key handling without an adapter. An engine that rejects synthetic events (isTrusted is false), polls physical devices or requires pointer lock, gamepads or a real user gesture needs its native controls or an engine integration; the platform cannot bypass those checks. Keep your own touch controls available alongside the overlay. Test your game's touch handling and release held actions on cancellation, blur and exit.

Touching an editable field inside your app can focus it and open the phone's normal keyboard under the browser's usual rules. The platform does not block that touch or suppress the native keyboard. The optional virtual Keyboard is a fallback: tap an app field or game surface first, then enable it. Supported editable fields receive text input that respects beforeinput cancellation, disabled/read-only fields and text-length limits. With no editable field selected, ordinary canvas/game handlers can receive untrusted keyboard events instead. The virtual keyboard can remain visible with Game buttons and supports capitalization, Backspace and Enter without granting browser shortcuts or privileged input. An action label or keyboard mapping does not implement game behavior or saving; your game still handles the selected action, and JavaScript progress still needs capture and restore as described above.

The player sound button overrides audio and video elements and supported Web Audio output in the main app document. It does not start playback by itself: browsers still require a real user gesture where autoplay is restricted. Audio in external embedded frames or unsupported audio APIs may require your own mute integration. Include native volume controls when useful and listen for hackemist:audiochange if you want to reflect the player's mute choice. Your own controls can coexist with the platform overlay.

Multiplayer, quizzes and chat

Enable built-in rooms under App details → Browser compatibility when the administrator has enabled the room service. Integrate Hackemist.multiplayer in your source to create or join rooms, invite people by code or link, listen to presence and messages, and coordinate shared state. Merely enabling rooms does not turn a single-player game into multiplayer. Read the multiplayer SDK guide for host authority, shared-state revisions, reconnect handling, locks and moderation.

Treat every client message as untrusted. Validate its type, length, permission and game rules before applying it. Keep messages small, rate-limit user actions, handle disconnected players, and avoid sending private account data to the room. Design chat moderation and reporting appropriate to your audience. Built-in rooms are live, ephemeral sessions and can be lost on service restart. They are not an authoritative anti-cheat server or a durable database. Persist durable results through an appropriate backend or account-save integration.

External APIs and backend integrations

Host backend code separately, for example an API, authoritative multiplayer server, database gateway or graphics processing service. In Studio, request exact HTTPS or WSS connection origins under Browser compatibility. The administrator reviews these requests. Use separate approved asset, frame and form origins where needed. Wildcards and arbitrary server access are not granted automatically.

Configure your backend's CORS for the actual isolated runtime origins. Apps can use different origins for each account and project; do not assume the control site's origin is the browser app origin. An opaque sandbox can send Origin: null; prefer approved isolated origins and deliberate CORS rules rather than permissive credentialed cross-origin access. Use HTTPS/WSS in production. Test connection failures, timeouts, reconnects and quotas.

Use a backend-controlled sign-in or scoped short-lived authorization flow when your service requires authentication. Hackemist session cookies and MCP tokens are not exposed to uploaded apps, and Hackemist does not turn external requests into authenticated account requests. Never put a privileged database key, provider API key, service account credential or MCP token in frontend code. A proxy on your own backend can keep provider credentials private and enforce per-user limits. Servers must verify authorization on every operation, validate input and enforce their own access controls.

Workers, WASM and graphics

Request the capabilities your export actually needs: workers, managed service-worker support, shared memory, embedded frames and approved network assets. Multithreaded WebAssembly requires shared-memory approval and compatible cross-origin isolation. Test your engine's export in the actual player. GPU features depend on the player's browser, device and driver; provide a fallback or list the requirement clearly. A platform permission cannot make an unsupported GPU API available on a device.

Stream large assets, compress textures appropriately, clean up workers/audio/GPU resources on exit, and avoid busy loops. Test resource use on a modest phone as well as a desktop. Document device targets, input controls, orientation, languages and accessibility in your listing. Include useful screenshots, a thumbnail, a short demo and accurate performance requirements.

Publish and maintain

Choose the correct category and subcategory, useful tags, a clear description and rich listing details. Upload your media or use the authorized AI capture workflow. Validate the draft, run publishing checks and try the preview before publishing. Resolve missing files, console errors, blocked network requests and unsafe dependencies. Keep private test drafts private. The published version remains visible while you edit a new draft; republish changes deliberately.

Public listings appear in discovery according to eligibility and the administrator's homepage selections. Trending combines eligible weekly positive reviews, eligible all-time reviews and distinct verified qualified players. Repeated opens, self-play, demo activity and guests do not inflate the qualified-player metric. Weekly rankings use eligible positive reviews from the current UTC week. Provide a complete app instead of trying to manipulate rankings.

Respect community rules, copyright, licenses, privacy and age-appropriate content. Collect only necessary information, explain external services, obtain permission where needed, and provide deletion and support paths for data held by your own backend. Avoid deceptive payment prompts, malware, hidden tracking and unauthorized copyrighted content. Use Hackemist's reporting/contact channels for safety and rights requests.

Publish with an AI assistant

MCP supports compatible clients through the account's approved connection, current subscription entitlement and scoped authorization. Read hosting_info and the platform documentation first. Agents can create projects, upload static builds, fill metadata and listing fields, upload or capture thumbnail/screenshots/demo video, request reviewed connections, configure saves/rooms and player controls, validate, and run the complete release workflow.

Use runtime_options_get followed by runtime_options_update with the current policy_revision for saves and rooms. Use connections_request for external services and player_controls_get/player_controls_update for touch mappings. Preserve version and revision guards when changing files, settings or media. Read project_release_checklist, fill missing fields and call project_release for browser checks and publication. An agent cannot bypass security review, operator-disabled capabilities, publishing checks or revoked authorization. Manual Studio publishing remains available without an MCP subscription.

Support: support@hackemist.com. Detailed SDK, multiplayer and deployment guides are included in the repository and available as MCP documentation resources.