Arcadible Manifest

The manifest describes your game: its identity, its store page, and how to build it. Most of its values are computed from files your project already has, so the store page is versioned and reviewed alongside your code.

A typical arcadible.toml is short:

arcadible.toml

[game]
id = "3f0c9a52-8d1e-4f7b-9a26-5b1c0e7d4a18"
handle = "star-drift"
genres = ["arcade", "action"]
audience = "everyone"
ai = "unused"
orientation = "landscape"
inputs = ["keyboard", "gamepad"]
visibility = "unlisted"

Sources

The CLI builds the manifest by merging these sources, in order. A field set in a later source overrides the same field from an earlier one.

#	Source	Provides
1	README.md (or arcadible.md if present)	title, short_title, tagline, bio, description
2	.arcadible/	icon, cover, banner, poster, splash, their _video variants, and gallery
3	package.json, if present	version and workflow.build
4	arcadible.toml	Everything else

If your project uses a package.json, the CLI reads its version, and builds with its build script, so you don't have to keep a second version number in arcadible.toml.

To leave an optional field unset, leave it out. An empty value, such as tagline = "" or genres = [], fails validation. The exception is build, where build = "" or build = [] means there's no build step, even if package.json has one.

Arcadible ignores fields and tables it doesn't know: they're left out of what arc inspect prints and what's deployed. arc validate warns about each, with the name it might mean when one is close, without failing.

To see the result, run arc inspect. It prints the fully resolved manifest, which is exactly what arc validate checks and what gets deployed.

arc inspect               # the whole manifest, as TOML
arc inspect game.title    # a single value
arc inspect --json        # machine-readable
arc validate              # check it against the rules on this page

Only the [game] table is published with the build. The [workflow] table is only used locally and in CI.

Media files

Media is read from the .arcadible/ directory. Art uses fixed file names, so you don't need to reference it anywhere, and the gallery's screenshots are picked up by name:

.arcadible/
├── icon.png            icon_video.mp4
├── cover.png           cover_video.mp4
├── banner.png          banner_video.mp4
├── poster.png          poster_video.mp4
├── splash.png          splash_video.mp4
└── gallery/
    ├── screenshot_01.png
    └── boss_fight.mp4

Each piece of art has a fixed aspect ratio and a range of allowed sizes:

Field	File	Ratio	Dimensions
icon	icon.png, icon_video.mp4	1:1	Minimum: 512 × 512 Maximum: 2048 × 2048
cover	cover.png, cover_video.mp4	3:2	Minimum: 768 × 512 Maximum: 3072 × 2048
banner	banner.png, banner_video.mp4	2:1	Minimum: 1024 × 512 Maximum: 4096 × 2048
poster	poster.png, poster_video.mp4	2:3	Minimum: 512 × 768 Maximum: 2048 × 3072
splash	splash.png, splash_video.mp4	16:9	Minimum: 1024 × 576 Maximum: 4096 × 2304
gallery	gallery/*.png, gallery/*.mp4	Any	Minimum: 512 × 512 Maximum: 2048 × 2048

Where each piece may appear in the store, and how to make it read well there, is in Your Store Page, with each piece's recommended size and edge margin.

These rules apply to every media field:

Format	File size	Duration	Video track
PNG	Maximum: 2 MB	—	—
MP4	Maximum: 15 MB	Minimum: 3 seconds Maximum: 30 seconds	Required

• Aspect ratios are exact. 1024 × 512 is 2:1, and 1030 × 512 is rejected.
• The maximum is four times the minimum on each side. A banner can be anywhere from 1024 × 512 to 4096 × 2048, as long as it's exactly 2:1.
• File names are case-sensitive. Use lowercase names and extensions: Icon.PNG isn't detected.
• Videos are optional companions. Each _video field is a variant that may play in place of its image, without sound, such as icon_video.

Media is public. .arcadible/ is published with the build, so its files can be downloaded from the build's origin. Don't put anything private there.

game

Describes the game and its store page. It's published with every build. What applies to every field, such as leaving an optional one out rather than empty, is in Sources; what applies to every media file is in Media files.

id

The permanent identifier of your game.

Rule	Value
Source	arcadible.toml
Required	Yes
Length	36 characters
Characters	Lowercase letters a–f, digits, and hyphens
Format	UUID (RFC 9562), such as one from arc init

Notes

• arc init generates it. Running arc init in an existing project adds one, and a version of 0.1.0-beta.1 if neither arcadible.toml nor package.json has one. When it adds either, it rewrites arcadible.toml, so comments and formatting aren't kept.
• Commit it and never change it. If you do, Arcadible treats the project as a different game.
• Once a game is deleted in Arcadible Studio, its id can't be deployed again. Deleting is immediate and can't be undone; to publish the project again, give it a new id.

version

The version of the build.

Rule	Value
Source	version in package.json (or arcadible.toml without one)
Required	Yes, unless package.json has a version
Format	Normalized semver, in lowercase: 1.2.0, not v1.2.0, 1.2, 1.2.0+build.1, or 1.2.0-Beta.1

Notes

• Each version can be published once. Bump it for every deploy. If a deploy fails before its build is published, you can deploy the same version again.
• A prerelease version such as 1.3.0-beta.1 is deployed to the staging channel. Any other version goes to production. Play a channel with arc play -r staging.

handle

A human-readable name used in URLs, such as play.arcadible.com/star-drift/.

Rule	Value
Source	arcadible.toml
Required	No
Length	Minimum: 3 characters Maximum: 24 characters
Characters	Lowercase letters, digits, and hyphens
Format	Starts and ends with a letter or digit, and doesn't contain --

Example

[game]
handle = "star-drift"

Notes

• It must be unique among games, and some names are reserved. arc deploy refuses a handle another game owns, one held for another account, or a reserved one. Only arc deploy changes a handle: a release from arc deploy git must carry the game's current one (game_handle_changed).
• Your first deploy claims it, even if it's a prerelease. After that, only a release version can change it.
• Until a game's first production release, it keeps its handle for 90 days, and your unreleased games hold at most 5 handles. See Limits › Handles.
• When it changes, links with the old handle stop working, and the old handle is held for your account for 30 days. Links with the game's id keep working as long as the game exists.
• Deleting a game in Arcadible Studio holds its handle for your account for 30 days.
• Without a handle, the game is addressed by its id.

title

The game's name.

Rule	Value
Source	The first # heading of README.md (or arcadible.md if present)
Required	No
Length	Maximum: 30 characters
Characters	Letters, digits 0–9, spaces, and . , ! ? ' " ( ) : ; -
Format	Plain text

Example

# Star Drift

Notes

• The character set excludes curly quotes, &, /, and emoji.
• Accented letters must be precomposed (NFC). A letter followed by a combining accent is rejected.

short_title

A shorter name for places where the full title doesn't fit, such as under an icon.

Rule	Value
Source	A parenthesized suffix on the # heading of README.md (or arcadible.md if present), or arcadible.toml
Required	No
Length	Maximum: 15 characters
Characters	Letters, digits 0–9, spaces, and . , ! ? ' " ( ) : ; -
Format	Plain text

Example

# Star Drift: Beyond the Rim (Star Drift)

That heading gives title = "Star Drift: Beyond the Rim" and short_title = "Star Drift". Each has its own limit: the short title doesn't count toward the title's 30 characters.

Notes

• When short_title is set in arcadible.toml, the entire heading is read as the title word for word, parentheses included.

tagline

A one-line hook.

Rule	Value
Source	The ## heading right after the # title in README.md (or arcadible.md if present)
Required	No
Length	Maximum: 30 characters
Characters	Letters, digits 0–9, spaces, and . , ! ? ' " ( ) : ; -
Format	Plain text

Example

# Star Drift

## Drift. Dodge. Survive.

Notes

• Without one, lists show the game's genres in its place.

bio

The game's pitch. It's shown in About when there's no description, and may appear, cut to two lines, where the game is featured.

Rule	Value
Source	The paragraph directly after the tagline in README.md (or arcadible.md if present)
Required	No
Length	Maximum: 180 characters
Characters	Letters, digits 0–9, spaces, and . , ! ? ' " ( ) : ; -
Format	Plain text

Notes

• Formatting is ignored, so write it as plain text.
• Put nothing between the tagline and the bio, or the README has no bio. See Arcadible Markdown.

description

The long-form About section on the store page.

Rule	Value
Source	The content between the first and last --- in README.md (or arcadible.md if present)
Required	No
Length	Maximum: 3,000 characters
Characters	Printable text and line breaks, without tabs or zero-width joiners
Format	Arcadible Markdown, limited to the allowed elements

Notes

• If the README has anything after its title, tagline, and bio, it must have at least two --- rules. See Structure.
• The length is measured on the rendered HTML, so tags and URLs count too.
• Images and videos must come from .arcadible/gallery/.

genres

The game's genres, used to group it in the store.

Rule	Value
Source	arcadible.toml
Required	No
Default	None
Count	Maximum: 3

Values

Value	Shown as
action	Action
adventure	Adventure
arcade	Arcade
board	Board
card	Card
casino	Casino
casual	Casual
music	Music
puzzle	Puzzle
racing	Racing
rpg	RPG
simulation	Simulation
sports	Sports
strategy	Strategy
trivia	Trivia
word	Word

Example

[game]
genres = ["puzzle", "casual"]

Notes

• Each genre can appear only once.

audience

Who the game's content is suitable for. It's shown to players on the store page.

Rule	Value
Source	arcadible.toml
Required	No
Default	everyone

Values

Value	Label	Description
everyone	Everyone	May contain minimal cartoon, fantasy or mild violence and/or infrequent use of mild language.
mature	Mature	May contain intense violence, blood and gore, sexual content and/or strong language.

For how to choose, see Choosing an audience.

Notes

• When you're unsure, choose mature. See Choosing an audience.
• The audience is part of every deploy. If an update adds more intense content, change the audience in the same release.

ai

Discloses whether generative AI created content that players can see or hear, before release or while they play. When it's generative, the store page shows a label telling players so. unused shows no label. AI used as a tool, such as to help write code for a game a person designed, doesn't count; a game an agent made does, its text and levels included, whether as files or in its code. See Your Store Page.

Rule	Value
Source	arcadible.toml
Required	No
Default	None, and the game's AI use is recorded as unknown

Values

Value	Label	Description
unused	No label	Generative AI created no content that players can see or hear.
generative	Generative	Generative AI created some of the content players see or hear, in whole or in part, before release or while they play.

For how to choose, see Disclosing AI.

Notes

• If you leave ai out, no label is shown, but your game's AI use is recorded as unknown rather than unused. Set it explicitly so it reflects your answer.
• AI used as a tool, such as to help write code, doesn't count. See Disclosing AI.
• The disclosure is part of every deploy. If an update adds generated content, change it in the same release.

orientation

The screen orientation the game expects.

Rule	Value
Source	arcadible.toml
Required	No
Default	natural

Values

Value	Meaning
natural	The device's natural orientation
any	Any orientation, with rotation allowed
portrait, landscape	Either direction of that orientation
portrait-primary, portrait-secondary, landscape-primary, landscape-secondary	A single, fixed direction

Example

[game]
orientation = "landscape"

Notes

• The Arcadible app uses it to shape its window.
• On a phone or tablet held the other way, a game that declares portrait or landscape (or one of their directions) gets Arcadible's prompt to turn it, with or without the SDK: it holds the loading screen until the device turns, and covers the game whenever it's held the other way during play. You need no rotate screen of your own. natural and any never get the prompt. See Best Practices › Fill the window.
• The values mirror the Screen Orientation API.

inputs

The input methods the game supports.

Rule	Value
Source	arcadible.toml
Required	No
Default	None

Values

Value	Meaning
keyboard	Keyboard only
mouse	Mouse only
keyboard-mouse	Keyboard and mouse together
gamepad	Gamepad
gamepad-motion	Gamepad with motion controls
touch	Touchscreen
touch-motion	Touchscreen with device motion
motion	Device motion only

For how to choose, see Declaring inputs.

Example

[game]
inputs = ["keyboard", "gamepad"]

Notes

• Each input can appear only once.
• If you leave inputs out, the store page doesn't list your game's inputs. Set it so players know how to play.

visibility

Whether the game is listed in the store and in search.

Rule	Value
Source	arcadible.toml
Required	No
Default	unlisted

Values

Value	Meaning
unlisted	Anyone with the link can play the game, but it isn't listed in the store or in search
public	The game is listed

Notes

• Like the rest of the store page, it changes only with a release version. See Visibility.
• arc validate warns when a release version leaves it out (field_unset). Set it either way to say which you mean.

trailer

A link to the game's trailer video.

Rule	Value
Source	arcadible.toml
Required	No
Length	Maximum: 255 characters
Format	An https YouTube or Vimeo URL

Example

[game]
trailer = "https://www.youtube.com/watch?v=…"

Notes

• These forms are accepted: youtube.com/watch?v=…, youtube.com/embed/…, youtu.be/…, vimeo.com/<id>, and player.vimeo.com/video/<id>.

icon

The game's icon. It may appear as the app icon, in lists and the library, and on the store page.

Rule	Value
Source	.arcadible/icon.png
Required	No
Format	PNG
Aspect ratio	1:1
Dimensions	Minimum: 512 × 512 Maximum: 2048 × 2048
File size	Maximum: 2 MB

Notes

• The aspect ratio is exact, and the name is case-sensitive: Icon.PNG isn't found.
• For text in art, see Text in art.

cover

Landscape art. It may appear in search results, and in link previews when the game is shared.

Rule	Value
Source	.arcadible/cover.png
Required	No
Format	PNG
Aspect ratio	3:2
Dimensions	Minimum: 768 × 512 Maximum: 3072 × 2048
File size	Maximum: 2 MB

Notes

• The aspect ratio is exact, and the name is case-sensitive: Cover.PNG isn't found.
• For text in art, see Text in art.

banner

Wide art. It may appear in featured spots and in wide headers, such as on phones.

Rule	Value
Source	.arcadible/banner.png
Required	No
Format	PNG
Aspect ratio	2:1
Dimensions	Minimum: 1024 × 512 Maximum: 4096 × 2048
File size	Maximum: 2 MB

Notes

• The aspect ratio is exact, and the name is case-sensitive: Banner.PNG isn't found.
• For text in art, see Text in art.

poster

Tall art. It may appear on tall cards and in headers.

Rule	Value
Source	.arcadible/poster.png
Required	No
Format	PNG
Aspect ratio	2:3
Dimensions	Minimum: 512 × 768 Maximum: 2048 × 3072
File size	Maximum: 2 MB

Notes

• The aspect ratio is exact, and the name is case-sensitive: Poster.PNG isn't found.
• For text in art, see Text in art.

splash

Background art. It may appear behind the game's title and text, blurred or tinted, and it's the game's loading screen while it starts (Initialization).

Rule	Value
Source	.arcadible/splash.png
Required	No
Format	PNG
Aspect ratio	16:9
Dimensions	Minimum: 1024 × 576 Maximum: 4096 × 2304
File size	Maximum: 2 MB

Notes

• The aspect ratio is exact, and the name is case-sensitive: Splash.PNG isn't found.
• For text in art, see Text in art.

icon_video

A video of icon, which may play once in its place, without sound, and then fade to it. Provide icon.png too, for places that don't show video.

Rule	Value
Source	.arcadible/icon_video.mp4
Required	No
Format	MP4
Aspect ratio	1:1
Dimensions	Minimum: 512 × 512 Maximum: 2048 × 2048
File size	Maximum: 15 MB
Duration	Minimum: 3 seconds Maximum: 30 seconds
Video track	Required

Notes

• The aspect ratio is exact, and the name is case-sensitive: Icon_Video.MP4 isn't found.
• arc validate warns when it has no icon.png beside it (art_video_unpaired).

cover_video

A video of cover, which may play once in its place, without sound, and then fade to it. Provide cover.png too, for places that don't show video.

Rule	Value
Source	.arcadible/cover_video.mp4
Required	No
Format	MP4
Aspect ratio	3:2
Dimensions	Minimum: 768 × 512 Maximum: 3072 × 2048
File size	Maximum: 15 MB
Duration	Minimum: 3 seconds Maximum: 30 seconds
Video track	Required

Notes

• The aspect ratio is exact, and the name is case-sensitive: Cover_Video.MP4 isn't found.
• arc validate warns when it has no cover.png beside it (art_video_unpaired).

banner_video

A video of banner, which may play once in its place, without sound, and then fade to it. Provide banner.png too, for places that don't show video.

Rule	Value
Source	.arcadible/banner_video.mp4
Required	No
Format	MP4
Aspect ratio	2:1
Dimensions	Minimum: 1024 × 512 Maximum: 4096 × 2048
File size	Maximum: 15 MB
Duration	Minimum: 3 seconds Maximum: 30 seconds
Video track	Required

Notes

• The aspect ratio is exact, and the name is case-sensitive: Banner_Video.MP4 isn't found.
• arc validate warns when it has no banner.png beside it (art_video_unpaired).

poster_video

A video of poster, which may play once in its place, without sound, and then fade to it. Provide poster.png too, for places that don't show video.

Rule	Value
Source	.arcadible/poster_video.mp4
Required	No
Format	MP4
Aspect ratio	2:3
Dimensions	Minimum: 512 × 768 Maximum: 2048 × 3072
File size	Maximum: 15 MB
Duration	Minimum: 3 seconds Maximum: 30 seconds
Video track	Required

Notes

• The aspect ratio is exact, and the name is case-sensitive: Poster_Video.MP4 isn't found.
• arc validate warns when it has no poster.png beside it (art_video_unpaired).

splash_video

A video of splash, which may play once in its place, without sound, and then fade to it. Provide splash.png too, for places that don't show video.

Rule	Value
Source	.arcadible/splash_video.mp4
Required	No
Format	MP4
Aspect ratio	16:9
Dimensions	Minimum: 1024 × 576 Maximum: 4096 × 2304
File size	Maximum: 15 MB
Duration	Minimum: 3 seconds Maximum: 30 seconds
Video track	Required

Notes

• The aspect ratio is exact, and the name is case-sensitive: Splash_Video.MP4 isn't found.
• arc validate warns when it has no splash.png beside it (art_video_unpaired).

gallery

Every PNG and MP4 in .arcadible/gallery/, sorted by file name. The gallery serves two purposes:

• Screenshots for the store page carousel.
• Media to embed in the description, using Markdown image syntax.

Rule	Value
Source	.arcadible/gallery/
Required	No
Count	Maximum: 24 files

Images

Rule	Value
Source	.arcadible/gallery/*.png
Required	No
Format	PNG
Aspect ratio	Any
Dimensions	Minimum: 512 × 512 Maximum: 2048 × 2048
File size	Maximum: 2 MB

Videos

Rule	Value
Source	.arcadible/gallery/*.mp4
Required	No
Format	MP4
Aspect ratio	Any
Dimensions	Minimum: 512 × 512 Maximum: 2048 × 2048
File size	Maximum: 15 MB
Duration	Minimum: 3 seconds Maximum: 30 seconds
Video track	Required

Notes

• Images and videos count together toward the 24-file limit.
• File names must be unique once the extension is removed. boss_fight.png and boss_fight.mp4 can't both exist.
• Extensions must be lowercase: .png and .mp4. Files with any other extension, including .PNG and .MP4, are skipped by the directory scan.

workflow

Describes how to turn the repository into a deployable directory. It's used by arc deploy, arc serve, and the GitHub release workflow, and it isn't part of the published manifest.

build

A shell command, or a list of commands joined with &&, run from the project root.

Rule	Value
Source	<package manager> run build when package.json has a build script (or arcadible.toml)
Required	No
Default	"", so no build runs

Notes

• Without a build in arcadible.toml, a package.json with a build script builds with the package manager its lockfile names, as you would locally: npm run build for package-lock.json or npm-shrinkwrap.json (or no lockfile), pnpm run build for pnpm-lock.yaml, and yarn run build for yarn.lock (with more than one, the first in that order), so its tools are found (with Yarn's Plug'n'Play too), and prebuild and postbuild run. To skip that script, set build = "".

• A list is useful for multiple steps:

  [workflow]
  build = ["./fetch-assets.sh", "./build.sh"]

• The command must produce deploy_dir.

deploy_dir

The directory that gets deployed.

Rule	Value
Source	arcadible.toml
Required	No
Default	.arcadible-public
Format	A relative path to a directory inside the project, such as dist, but not the project root, and not inside .arcadible/
Contents	An index.html at its root, which is the entry point players load
Size	Maximum: 64 MB, compressed

Example

[workflow]
deploy_dir = "dist"

Notes

• It must already exist unless a build step creates it.
• Its root can't contain arcadible.json or .arcadible. They're reserved for the files Arcadible adds when it packages the game.
• Its root can't contain an arcadible folder either, in any letter case. Every game's address keeps /arcadible/ for Arcadible's own files.
• The packed game, meaning deploy_dir and .arcadible/, can be up to 256 MB uncompressed, in at most 10,000 files of up to 64 MB each.