Loading article…

Loading 4weird…

DocsPlugin checklist

Docs · studio · plugins

Validate first. Mount second.

The /games/mods browser mounts community mods and themes only after they validate: a typed manifest, an allow-listed permission set, curated theme tokens, and a sandboxed iframe. Run this checklist before submitting and your plugin passes first try.

5: target scopes
5: permissions max
6: curated tokens
0: auto-granted perms

Manifest

Shape your manifest exactly

Every submission is validated by validateGameModManifest, which never throws — it returns { ok, errors, manifest } so bad rows drop fail-open. Mirror this shape and the error list stays empty.

manifest.json — ember-arsenal-pack (valid)

validates clean

name / slugEmber Arsenal Pack / ember-arsenal-pack

version / target_game1.2.0 / gravegain3d

script_urlhttps://…/ember-pack.js

permissionsstorage:local, audio:play

Checklist

Seven checks before you submit

Each check maps to a real validation rule. Fail any of them and the row is dropped with errors listed — fix, resubmit, no harm done.

Name it, slug it
Provide a display name and a URL-safe slug matching ^[a-z0-9-]+$, unique per catalog. Slugs are the identity — renames are new submissions.
Version it semver-ish
Use major.minor.patch with an optional prerelease suffix (e.g. 1.2.0, 2.0.0-beta.1). Anything else fails version validation.
Target one scope
Set target_game to gravegain3d, gravegain2d, gravegain1d, battlesharks2, or global. New games never need a validator change — any slug-shaped scope is accepted.
Declare only allow-listed permissions
Request from storage:local, audio:play, interop:emit, clipboard:read, clipboard:write — and nothing else. Permissions are declaration-only today and the mount grants none automatically; an unknown permission fails validation instead of being ignored.
Theme with --* tokens
Theme keys must match --*. The shell applies the six curated tokens (--mod-bg, --mod-fg, --mod-accent, --mod-panel, --mod-border, --mod-font); extra keys ride along forward-compatibly.
Serve the bundle from https
Point script_url at an https:// bundle (relative paths allowed for first-party dev). The mount runs it in an allow-scripts-only sandboxed iframe, and only 4weird.com origins are trusted.
Preview in the browser first
Open /games/mods: the browser validates every row locally and ignores invalid entries, so you see exactly what reviewers see — including the offline fallback bundle when the future live catalog endpoint isn't wired yet.

Worked example

Fix a failing manifest in three passes

A typical first submission fails on two or three small shape errors. The browser lists each one, so fix exactly what it names, resubmit, and watch the row validate clean.

Pass 1: read the error list
Open the mods browser and find your row. A result like { ok: false, errors: ["slug", "version"] } names the guilty fields. Copy the slug error first since identity problems cascade.
Pass 2: repair slug and version
Lowercase the slug to match ^[a-z0-9-]+$ (for example Ember Pack! becomes ember-pack) and confirm uniqueness in the catalog. Rewrite the version as 1.2.0 or a suffixed prerelease like 2.0.0-beta.1. Retest locally before resubmitting.
Pass 3: trim permissions and theme keys
Keep only allow listed permissions such as storage:local and audio:play, and confirm every theme key starts with --. Serve the bundle over https, reload the browser, and confirm the valid badge appears.

FAQ

Review, verify, publish

What happens after validation passes, and what never happens automatically.

Does validation publish my plugin?
No. Validation only admits the row to the browser. Discovery, featuring, and the verified badge follow human review. A clean validation with an author handle gets reviewed fastest.
Can I claim verified in my manifest?
Setting is_verified yourself changes nothing. The flag mirrors a review column. Ship clean, get reviewed, earn the badge honestly.
Do declared permissions grant access?
Not today. Permissions are declaration only and the mount grants none automatically, inside an allow scripts only sandboxed iframe. Request the minimum set so reviewers trust the bundle.
Which target scope should I pick?
Match the game your mod actually touches: gravegain3d, gravegain2d, gravegain1d, or battlesharks2. Choose global only for genuinely cross game themes. New game slugs are accepted without validator changes.
The catalog endpoint looks dead. Is my mod lost?
No. The browser validates every row locally and falls back to the bundled catalog when the future live endpoint is not wired. If your row validates locally, reviewers see exactly what you see.

Loading article…

DocsPlugin checklist

Docs · studio · plugins

Validate first. Mount second.

5: target scopes
5: permissions max
6: curated tokens
0: auto-granted perms

Manifest

Shape your manifest exactly

Every submission is validated by validateGameModManifest, which never throws — it returns { ok, errors, manifest } so bad rows drop fail-open. Mirror this shape and the error list stays empty.

manifest.json — ember-arsenal-pack (valid)

validates clean

name / slugEmber Arsenal Pack / ember-arsenal-pack

version / target_game1.2.0 / gravegain3d

script_urlhttps://…/ember-pack.js

permissionsstorage:local, audio:play

Checklist

Seven checks before you submit

Each check maps to a real validation rule. Fail any of them and the row is dropped with errors listed — fix, resubmit, no harm done.

Name it, slug it
Provide a display name and a URL-safe slug matching ^[a-z0-9-]+$, unique per catalog. Slugs are the identity — renames are new submissions.
Version it semver-ish
Use major.minor.patch with an optional prerelease suffix (e.g. 1.2.0, 2.0.0-beta.1). Anything else fails version validation.
Target one scope
Set target_game to gravegain3d, gravegain2d, gravegain1d, battlesharks2, or global. New games never need a validator change — any slug-shaped scope is accepted.
Declare only allow-listed permissions
Request from storage:local, audio:play, interop:emit, clipboard:read, clipboard:write — and nothing else. Permissions are declaration-only today and the mount grants none automatically; an unknown permission fails validation instead of being ignored.
Theme with --* tokens
Theme keys must match --*. The shell applies the six curated tokens (--mod-bg, --mod-fg, --mod-accent, --mod-panel, --mod-border, --mod-font); extra keys ride along forward-compatibly.
Serve the bundle from https
Point script_url at an https:// bundle (relative paths allowed for first-party dev). The mount runs it in an allow-scripts-only sandboxed iframe, and only 4weird.com origins are trusted.
Preview in the browser first
Open /games/mods: the browser validates every row locally and ignores invalid entries, so you see exactly what reviewers see — including the offline fallback bundle when the future live catalog endpoint isn't wired yet.

Worked example

Fix a failing manifest in three passes

A typical first submission fails on two or three small shape errors. The browser lists each one, so fix exactly what it names, resubmit, and watch the row validate clean.

Pass 1: read the error list
Open the mods browser and find your row. A result like { ok: false, errors: ["slug", "version"] } names the guilty fields. Copy the slug error first since identity problems cascade.
Pass 2: repair slug and version
Lowercase the slug to match ^[a-z0-9-]+$ (for example Ember Pack! becomes ember-pack) and confirm uniqueness in the catalog. Rewrite the version as 1.2.0 or a suffixed prerelease like 2.0.0-beta.1. Retest locally before resubmitting.
Pass 3: trim permissions and theme keys
Keep only allow listed permissions such as storage:local and audio:play, and confirm every theme key starts with --. Serve the bundle over https, reload the browser, and confirm the valid badge appears.

FAQ

Review, verify, publish

What happens after validation passes, and what never happens automatically.

Does validation publish my plugin?
No. Validation only admits the row to the browser. Discovery, featuring, and the verified badge follow human review. A clean validation with an author handle gets reviewed fastest.
Can I claim verified in my manifest?
Setting is_verified yourself changes nothing. The flag mirrors a review column. Ship clean, get reviewed, earn the badge honestly.
Do declared permissions grant access?
Not today. Permissions are declaration only and the mount grants none automatically, inside an allow scripts only sandboxed iframe. Request the minimum set so reviewers trust the bundle.
Which target scope should I pick?
Match the game your mod actually touches: gravegain3d, gravegain2d, gravegain1d, or battlesharks2. Choose global only for genuinely cross game themes. New game slugs are accepted without validator changes.
The catalog endpoint looks dead. Is my mod lost?
No. The browser validates every row locally and falls back to the bundled catalog when the future live endpoint is not wired. If your row validates locally, reviewers see exactly what you see.

Validate first. Mount second.

Shape your manifest exactly

Seven checks before you submit

Name it, slug it

Version it semver-ish

Target one scope

Declare only allow-listed permissions

Theme with --* tokens

Serve the bundle from https

Preview in the browser first

Fix a failing manifest in three passes

Pass 1: read the error list

Pass 2: repair slug and version

Pass 3: trim permissions and theme keys

Review, verify, publish

Does validation publish my plugin?

Can I claim verified in my manifest?

Do declared permissions grant access?

Which target scope should I pick?

The catalog endpoint looks dead. Is my mod lost?

Validate first. Mount second.

Shape your manifest exactly

Seven checks before you submit

Name it, slug it

Version it semver-ish

Target one scope

Declare only allow-listed permissions

Theme with --* tokens

Serve the bundle from https

Preview in the browser first

Fix a failing manifest in three passes

Pass 1: read the error list

Pass 2: repair slug and version

Pass 3: trim permissions and theme keys

Review, verify, publish

Does validation publish my plugin?

Can I claim verified in my manifest?

Do declared permissions grant access?

Which target scope should I pick?

The catalog endpoint looks dead. Is my mod lost?