Getting Started with Arcadible Game Development
This guide takes a new game from an empty directory to a public game on Arcadible, using a starter template. You deploy to staging first, make the store page your own, then release it to players. To publish a game you've already built, see Bring an Existing Game.
Before you begin
You need:
- An Arcadible account. Join at arcadible.com.
- Node.js 22 or later, to run the CLI. Your game doesn't need to use Node.js.
Install the CLI
The CLI is published to npm as arcadible, and its command is arc:
npm install -g arcadible
arc --version
Log in
arc login
arc login prints a link and a code. Open the link, enter the code, and log in, or scan the QR code with a phone. No password is typed into the terminal. Check which account you're using with:
arc whoami
See arc login for headless machines and where the session is stored.
Create a project
Start from a starter: a complete game that deploys as it is, with its store page, its art, and a save already in place. Each is one arc init command, such as:
arc init star-drift -y # the blank starter: HTML and JavaScript, with no build step
arc init star-drift -t arcadible/starters/threejs # Three.js and Vite
The Phaser, PixiJS, and Babylon.js starters are in Starter templates. Then:
cd star-drift
npm install # the Three.js, Phaser, PixiJS, and Babylon.js starters
arc init creates the folder, and installs nothing; neither does arc deploy, so an engine starter's build fails until npm install has run. Without -y or -t, it asks which starter to begin from, with the blank one as the default. Any public GitHub repository, or a folder in one, works as a template too: arc init star-drift -t user/repo.
Project structure
Every starter has the same project files:
star-drift/
├── arcadible.toml # the manifest
├── README.md # the store page
├── AGENTS.md # instructions for coding agents
├── .arcadible/ # the store art
│ ├── icon.png
│ ├── cover.png
│ ├── banner.png
│ ├── poster.png
│ ├── splash.png
│ └── gallery/ # screenshots, and the description's media
├── .arcadible-public/ # what players load
└── .github/workflows/
└── arcadible-release.yml # used by arc deploy git
arcadible.tomlis your Arcadible Manifest, and holds what can't be derived from anywhere else.arc inithas already given it a uniqueid; commit it and never change it.README.mdis your store page, written in Arcadible Markdown: its headings and paragraphs become the title, tagline, bio, and description.AGENTS.mdtells coding agents the commands, the rules, and which docs to read. See Working with AI Agents..arcadible/holds the art, each piece by a fixed name, fromicontosplash, so there's nothing to reference. Each piece can also have a video beside it, such assplash_video.mp4, which may play in the image's place. Each starter's placeholders are drawn at the recommended sizes, with each piece's edge margin marked.gallery/holds the images and videos for your screenshots and your README's description. Seegallery..arcadible-public/is yourdeploy_dir: what players load, and whatarc deploypackages.arcadible-release.ymlreleases from a tag, witharc deploy git.- The game already uses the Arcadible SDK: it starts its initialization as its code starts and completes it on its first frame, so Arcadible shows its loading screen until the game is drawn, and it keeps a save that carries over to its next version. Keep both as you make the game yours.
The game itself is where the starters differ:
| Blank | Three.js, Phaser, PixiJS, Babylon.js | |
|---|---|---|
| The game's source | index.html, main.js, and page.js in .arcadible-public/ | index.html, main.js, and page.js at the root, which Vite builds into .arcadible-public/ |
| The version | version in arcadible.toml | "version" in package.json |
| The Arcadible SDK | The hosted script, /arcadible/sdk/v1.js, in index.html | The package, @arcadible/sdk |
While you edit, run the game in a local play page, as Arcadible runs it, with arc serve: each starter's commands are in Testing Your Game.
Deploy to staging
The starters begin at a prerelease version, 0.1.0-beta.1, so your first deploy goes to staging: playable by link, but not shown to players. Deploy, and play it:
arc deploy
arc play
arc deploy validates the project, runs your build, packages the game with its store art, and starts a release. It waits until Arcadible has published the build, then prints where to play it, or says why the release failed. See Releases.
arc play opens the game in the Arcadible app, or a browser if the app isn't installed. Until the game has a production release, it opens staging. Each version publishes once, so bump the prerelease number, such as 0.1.0-beta.2, after each published build; a failed release's version deploys again (When a release fails). See Channels.
Make it yours
Give the game its own name, handle, and art: what makes its store page. None of it is required to deploy, so do it in any order, deploying to staging as you go. To see the store page each deploy would publish, open the game in Arcadible Studio, then its Store tab, under Staging.
-
Name it. Edit the headings and the bio in
README.md:README.md# Star Drift
## Drift. Dodge. Survive.
A one-thumb arcade game about surfing a dying star.
---
Pilot a freighter through **collapsing orbits**.
---The first heading is the title, the
##heading after it the tagline, the paragraph after that the bio, and everything between the first and last---the description. See Arcadible Markdown. -
Claim a handle. The handle is the name in your game's links, such as
play.arcadible.com/star-drift/. It's unique among games, and a game keeps it for 90 days until its first production release (Limits › Handles):arcadible.toml[game]
handle = "star-drift"The rest of
[game]is optional, such asgenres,inputs,audience, which the starter sets toeveryone, andai, which it leaves for you to answer: what each does is in Your Store Page. -
Replace the art. Swap the images in
.arcadible/and.arcadible/gallery/for your own, keeping the file names and aspect ratios, and keeping what matters inside the placeholders' edge margin. See Your Store Page and Screenshots.
Then check the project:
arc validate # the same checks arc deploy runs
arc inspect # the manifest as Arcadible sees it
arc validate lists every problem with a link to the rule it breaks. arc inspect shows where each value ended up, such as arc inspect game.title.
Release it
When the game is ready, release it to production with a version without a suffix, such as 0.1.0, then deploy:
arc deploy
arc open # open its store page
A production release becomes what players get, and builds the store page from your README, art, and manifest. See Releases for how it gets there, and how to roll one back. Your game is unlisted to start with (visibility): anyone with the link can play it, but it doesn't appear in the store or in search. Share the link with testers at this stage:
https://play.arcadible.com/star-drift/
To ship an update, change the game, bump the version, and deploy again. Try it on staging first with a prerelease, such as 0.2.0-beta.1, then release 0.2.0.
Go public
When you're ready for players to find it in the store and in search, set visibility = "public" and deploy a release version: see Going Public.
Release from GitHub
Instead of deploying from your machine, GitHub Actions can build each release from a tag: arc deploy git. The starters include the workflow it needs. See Deploying from GitHub to set it up.
Next steps
- How Arcadible Works: every term these docs use.
- Testing Your Game: locally, on staging, and on devices.
- Best Practices: loading, performance, input, and lifecycle for games on the web.
- Runtime: what the sandbox allows and blocks.
- Arcadible Studio: your games, their builds, and releases.