Send an AI persona through your build before a player does
Ravensight Playtest is a CLI you run against your own build. It hands your game to a handful of AI personas, each with a different way of playing, and brings back a written report per persona: what worked, what they got stuck on, and whether they would have kept playing. The personas' sessions land in the same dashboard as your real players, tagged so they never touch your real numbers unless you ask for them.
Before you start
You need Node 22 or later, a Ravensight game with an ingest key already set up, and a balance on your account. A playtest run spends from the same prepaid balance as everything else here: no card, no subscription, and nothing runs without balance to cover it.
Install the current runner
npm install --global ravensight-playtest
That puts the ravensight-playtest command on your path,
and every example below runs it directly.
Registering a run spends money, so it needs an admin role or above. Reading past jobs, findings and reports needs only a read-only role, and writing a brief or marking a finding needs a member role.
Playwright is an optional dependency, so login,
check, init and brief work on a
machine with no browser installed; only a web-driver run asks for one.
The credential store is optional too, which is why a machine with no
keychain still installs cleanly.
Sign in and point it at a game
The CLI never asks for a password and never holds a model provider key. Signing in mints a short device code, which you approve from the dashboard rather than typing anything back into the terminal.
Sign in
ravensight-playtest login
This prints a short code and a link. Open the link, or go to app.ravensight.io/cli and enter the code yourself, then pick which of your games the CLI should be able to touch. The terminal picks up the approval on its own once you confirm it.
The token lands in your operating system's credential store: macOS
Keychain, Windows Credential Manager, libsecret on Linux. With none
available it falls back to a file readable only by you, and says which
store it used. For CI, set RAVENSIGHT_TOKEN and skip
login entirely. logout revokes the token on
the server and forgets it locally, and deliberately leaves a token that
came from RAVENSIGHT_TOKEN alone, because that is probably
a CI secret other jobs share. An org owner can revoke every token a
member holds in that org at once from Settings.
A CLI token starts with gt_cli_, and only that kind works
with the CLI, in RAVENSIGHT_TOKEN as well. An MCP token
(gt_mcp_) is refused with a 401 that says
so and tells you to run ravensight-playtest login for a
CLI token. A game's ingest key (gt_live_) is refused with
403 ingest_key_not_allowed.
Connect a project to a game
ravensight-playtest init --game <gameId>
Run this once per project. It writes a small local config file next to your code so every later command knows which game it is talking about.
Connect your build
Ravensight Playtest plays web builds, in the cloud or on your own machine, and Godot projects on your own machine. Native desktop and mobile builds are not supported today: the CLI has experimental adapters for them, but each one needs an automation server you install and run yourself, and Ravensight does not provide one. Console builds need your own authorized tooling.
Choose a build type on the dashboard's Playtest page for its run command. The experimental desktop and mobile adapters talk to a local automation server that speaks the WebDriver protocol. Custom bridges exchange bounded game controls through JSON-RPC, with no model access to a shell. Read the complete adapter setup and protocol guide.
Which builds play where
A cloud playtest opens your build's HTML page in a browser on an
isolated machine, so it plays web builds only. A local playtest runs
on your own machine and plays web builds and Godot projects; for a
native desktop or mobile build it has only the experimental adapters
above.
To play an exported web folder locally, pass
--build-dir with the folder (CLI 0.7.6 or later): the CLI serves it with the
headers engine exports need (WebAssembly, Brotli and gzip files,
and the isolation a threaded build needs). --build-url
still plays a build you serve yourself.
| Engine | Cloud playtest (upload a ZIP) | Local playtest (CLI) |
|---|---|---|
| Godot 4 | Web export, with or without threads. The entry file is its page, index.html or the name you exported it under. | The web export with --build-dir, or the project itself with --driver godot_driver. |
| Unity | Web build. Use the export settings in Playtest a Unity game. | The web build with --build-dir. A native build is not supported today; --driver unity_driver is an experimental adapter that needs your own automation server. |
| LÖVE | The love.js output, standard or compatibility mode. | The love.js output with --build-dir. A desktop build only through an experimental adapter: --driver desktop_driver with your own automation server, or a custom bridge. |
| JavaScript and HTML5 | The built site, with its HTML page as the entry file. | --build-dir or --build-url. |
| C++ | An Emscripten build: its page, JavaScript and .wasm, threaded or not. | The Emscripten build with --build-dir. A desktop build only through an experimental adapter: --driver desktop_driver with your own automation server, or a custom bridge. |
| Odin | A js_wasm32 build with its page and odin.js. | The web build with --build-dir. A desktop build only through an experimental adapter: --driver desktop_driver with your own automation server, or a custom bridge. |
| Unreal | Not available: Unreal has no supported web export. | Not supported today. --driver unreal_driver is an experimental adapter that needs your own automation server. |
| iOS | Not available. | Not supported today. --driver ios_driver is an experimental adapter that needs your own automation server and a device or simulator. |
| Android | Not available. | Not supported today. --driver android_driver is an experimental adapter that needs your own automation server and a device or emulator. |
A cloud upload that is a desktop, mobile or Unreal build is refused
before anything is played, with the engine named and what to upload
instead. An entry file that is a program or a package (such as
.exe, .apk or .ipa) is refused
before the validation hold is taken; any other such build is refused
at its archive check and the hold is returned after cleanup. No
playtest is quoted or charged for a refused build.
Playtest a Unity game
A Unity game is playtested as a web build: export it for the Web platform and play that folder locally, or upload it as a ZIP for a cloud playtest. Both run the same build in a browser.
Export settings. In Player Settings for the Web platform:
- Compression Format: Disabled or Gzip. The local and cloud runs also serve Brotli files with their encoding, but a Brotli Unity export has not been checked end to end, so Disabled or Gzip is the safer choice.
- Decompression Fallback: off.
- Data Caching: off.
- WebGL Template: Default or Minimal, so the export has its
index.htmlat the top of the folder. Zip the folder's contents, soindex.htmlis at the root of the ZIP. - Resolution: a canvas around 960 by 600, so it fits the 1280 by 800 browser window the playtester uses.
- Run In Background: on, so the game keeps running when the page loses focus.
- No requests to other sites. The page may load only its own files. A cloud playtest has no network, and a build that loads anything from a web address is refused at its archive check.
Play the exported folder on your own machine
ravensight-playtest run --driver playwright_web --build-dir ./Builds/WebGL
Check the ZIP before a cloud upload (free, nothing is uploaded)
ravensight-playtest build preflight ./my-game-web.zip --format web
Then upload it with ravensight-playtest build upload or
from the dashboard, and start a run as in
Cloud playtests. The limits for a cloud
upload:
- One standard ZIP under 4 GiB, with no ZIP64, at most 5,000 files and folders at most 16 deep.
- Up to 4 GiB unpacked. The unpacked size picks the smallest tier that holds it: Jam up to 50 MiB, Small up to 250 MiB, Medium up to 1 GiB, Large up to 4 GiB.
- The dashboard uploads a ZIP of up to 300 MiB; a larger one goes through
ravensight-playtest build upload, which sends it in parts. - The entry page is an HTML file of at most 64 MB.
Everything is inside the canvas. Unity draws its whole
interface inside one canvas, so the page has no buttons or text the
playtester can read directly; it plays from screenshots, as it does any
canvas game. The run's own win check reads win wording in the page's
text, so a win shown only inside the canvas is not detected by it. To
tell the run your game is won, set
window.__ravensightWon = true from a small
.jslib plugin when the whole game is won. Play ends there,
so set it only for the final win, not a level clear.
A jslib plugin, saved under Assets/Plugins/WebGL
mergeInto(LibraryManager.library, {
RavensightMarkWon: function () { window.__ravensightWon = true; }
});
Call it from C# in the web build only
#if UNITY_WEBGL && !UNITY_EDITOR
[System.Runtime.InteropServices.DllImport("__Internal")]
private static extern void RavensightMarkWon();
#endif
void OnGameWon()
{
#if UNITY_WEBGL && !UNITY_EDITOR
RavensightMarkWon();
#endif
}
A Unity web build keeps its saves where the address it is served
from decides, so a save file is not placed for it: read
window.RavensightPlaytest.save at boot instead (see
A save to start from in Cloud playtests).
What is not supported. A native Unity build, desktop
or mobile, cannot be playtested today. The cloud accepts web builds
only and refuses a native Unity build, and no playtest is charged for it. The
CLI's unity_driver is an experimental adapter that needs
an automation server you install and run yourself, and Ravensight
does not provide one.
Cloud playtests: one playtester per persona
A cloud playtest plays your uploaded web build on our machines with one playtester per persona: Geri and Freki play your game together. Geri thinks: it reads each new screen, sets a goal and plans the next few inputs. Freki acts: it plays the routine steps of the plan and the repeats, and hands back to Geri when the screen surprises it. Each persona plays on its own cloud machine, at the same time as the others, and one report covers them all, with each persona's own report beside it.
- Personas.
fresh-eyes, a first time player, is always included. Tick any others in the dashboard, or name them with--personas; each adds its own price to the quote, which updates as you choose. - Tiers. Jam (builds under 50 MB, 5 minutes of play), Small (under 250 MB, 8 minutes), Medium (under 1 GB, 15 minutes) and Large (up to 4 GB, 30 minutes on a bigger machine). The default is the tier your build's unpacked size needs; a smaller one is refused before any hold or charge, with the build's real size and the tier to choose. The dashboard uploads a ZIP of up to 300 MB; a larger one, up to 4 GB, uploads with
ravensight-playtest build upload, which sends it in parts. - Video. A run of ten minutes or less saves one video. A longer run saves one part for each ten minutes it started, and the report plays them in order. Each is kept 90 days.
- Play length. Choose any length from the tier's own up to 120 minutes per persona. Geri's thinking budget and the action limit grow with it, and Geri's budget is spread over the whole run rather than spent in the first minutes.
- Focus. A start query or hash on your build (such as
?level=3), up to five goals that go to the top of every persona's plan ("beat the first boss"), and up to five things to stay out of ("the settings menu"). They are plain text with no links, and the report shows them at the top. - A save to start from.
--save <file>onhosted quoteandhosted runstarts every persona from your save file, at most 1 MiB.--save-targetsays where your game reads it:godot:user://saves/slot1.savfor a Godot web export,localstorage:<key>, oridbfs:/mount/pathfor another engine's browser file storage. The save is placed there before the game loads. Without a target, or for a game that keeps its save somewhere else (a Unity web build does), the game reads the file itself fromwindow.RavensightPlaytest.save, which has itsname,bytesand aurlto fetch. The dashboard does not upload a save yet. - The quote. One line per persona and a total, reserved in full from your prepaid balance before anything starts. When the cloud is busy, each persona shows its own queue place and expected start; a funded run is queued, not refused.
- Refunds. Each persona settles on its own under the ordinary refund rules. A persona that never gets a machine is refunded in full. The Large tier carries a non-refundable setup fee, a separate line in the quote, kept even when that persona is refunded, unless it never got a machine.
- A build too large for its tier. If a persona runs out of memory on its machine, or its frame rate stays under 3 frames a second for most of a minute of play while the game is drawing, that persona stops early and the report says what was measured. It keeps the machine time and model spend it used plus the under-scope fee shown on the quote, the rest of its price is refunded, and the report names the tier to choose.
A cloud playtest with two more personas, focused
ravensight-playtest hosted run --personas speedrunner,completionist \ --minutes 10 --start '?level=3' --focus "beat the first boss" \ --avoid "the settings menu" --wait
This needs CLI 0.9.0 or later; a ZIP over 300 MB and --save
need CLI 0.10.0. The dashboard's Run in the
Ravensight cloud page offers the same choices, with the live
total. Prices are in Usage rates and limits.
Read a cloud playtest report
Each persona's report has two lists. Findings are only what the run verified: the runner measured it (a control that did nothing when the page got the click, a script error, a crash, a blank screen), a check of the frame at that moment showed it, or a replay with no input showed the screen standing still. Playtester impressions are what the playtester felt and said that the run could not verify, in its own words: a matter of taste ("the icon is unclear") kept only when a check of the frame showed what it rests on, and its own liking. An opinion nothing the run saw supports is not kept, and a judgement of its own play ("too hard") is listed as a limit of the run. An impression can be wrong, and the report says so beside each one. What the frame or the run's record showed to be false is in neither list: it is listed with the reason under "Raised by the playtester, not confirmed".
- Top issues. The findings, each with its severity, its evidence (a screenshot or a time in the session video) and, where the persona said something, its own words. When there is none it says "None confirmed" and points to the lists below.
- Playtester impressions. Each impression with its step, the playtester's own words, the frame at that moment, its grade (the playtester's, except that a blocker the run's record does not support reads major, as a finding's would) and a note saying why it is not a finding. Impressions are never counted with the findings, never ranked, never put in what to fix first, and never kept as studio memory. The dashboard shows them after the findings, in a quieter list, and
report.jsoncarries them asimpressions. - Checks on the findings. Each issue is shown once against the frame at its moment and asked whether the frame shows it (for something the playtester says the game did, whether the game is at fault), shows the opposite, or cannot tell, and the recorded inputs are played again with no model to see whether the same thing happens. A claim that nothing happens counts as reproduced only when the screen stayed still while game time ran for two seconds with no input. A replay that could not test a claim says "not verifiable", and a check that was not made says so: neither is counted as passed.
- Raised by the playtester, not confirmed. What the playtester said that is neither a finding nor an impression, each with the reason: the run's own record or the frame contradicts it (it called the game stuck while the screen changed, or said something was missing that the run read on screen), the game was doing what it is meant to, it did not come back when tried again, it states a fact about the screen that nothing confirmed, or it is an opinion nothing the run saw supports. A false statement of fact is never relabelled as an impression. None of these is a finding about the game.
- Test charter. The areas to test, the risks for this kind of game and what a failure would look like, written before testing from the brief and the first screens. About one plan in four is a testing turn once play is under way, and the charter says how many turns each area got; an area that got none is listed as not tested.
- What was and was not tested. A table of the techniques a hired tester uses, each marked tested or not with the reason: rapid input on one control, every control play never pressed, controls out of order, text fields given nothing and far too much, a menu left and entered again, pause and resume, opposite keys held together, the edges of the play area, text cut off, sound output, input while the game loads, then focus loss, a resize, a mashed key, idling, the browser's Back button and a reload. These probes are scripted and ask no model. It then lists how a bug was recognised (script errors, a crash or a blank screen, a soft lock, the frame rate, the game's own numbers, placeholder text, a control that does nothing) and the screens and controls the run reached and did not. Not tested never means healthy.
- Limits: What this run didn't cover. Where the session never got to, and what the playtester could not read, press or confirm. Read it before the findings.
The job's own page has a Report tab beside the written reports. It rebuilds the same run, with no model call, as a list of what to fix first, each finding at its moment in the video, its checks, and the inputs that lead to it.
Record and compare local playthroughs
A local run can also be played by Geri alone or by Freki alone, or
by both separately for comparison. These options exist for
evaluation and are no longer listed in --help; a cloud
playtest is always the combined playtester above.
Geri reads each screen and chooses every action
itself. Freki proposes up to three actions on each
screen and lets a separate selector pick one. Freki proposes and never
decides: when the selector is unsure or cannot be reached, CLI 0.10.0
plays Freki's most likely candidate, or else the first action proposed
for that screen, and the step log says which. Both play the same persona from the same brief
at the same price.
These options require CLI 0.5.0 or later and a compatible server; the
geri and freki flag values below need CLI
0.8.0. The dashboard's local setup reads the server's current CLI
release and playtester capabilities before offering a comparison.
Install the runner it names; the CLI checks support again before
registration or charge. Web and Godot builds support this flow. For
cloud playtests of web builds, see
Which builds play where. The existing
hosted Linux headless simulation flow and its separate quote are
unchanged.
Compare one persona with Geri and Freki, keeping video local
ravensight-playtest run --driver playwright_web \ --build-url http://localhost:3000 --personas <persona-slug> \ --compare-with freki --record-video
Choose a persona from your game's pack. Each selected persona gets two
independent paid playthroughs and two reports, one with Geri and one
with Freki. Two personas mean four runs. The server quotes all runs together
at the existing per-run prices, and the CLI asks you to confirm that total
before charging your prepaid balance. At the current standard price,
one persona with both playtesters costs $12.80 for Playtest, or $16.40 with
--long. Freki's selections are included in its run; comparing
the reports does not add a model call or fee.
For a single explicit playtester, use --controller geri
or --controller freki instead of --compare-with freki.
Do not combine those flags. Omitting both preserves the configured
default. An unavailable playtester is refused before charge, rather
than silently replaced.
Record a rendered Godot project
ravensight-playtest run --driver godot_driver \ --godot-project ./your-game --personas <persona-slug> \ --compare-with freki --record-video
Godot needs the Ravensight addon, a rendered viewport and local FFmpeg. Web video records the selected Playwright page as WebM; Godot samples the selected viewport and creates an MP4. Neither records audio, your desktop or unrelated windows. Browser recording stays on the selected page and same-origin top-level navigation. A headless Godot process has no rendered scene to record.
--record-video keeps video on your computer.
--upload-video also records and explicitly opts in to sending
it to this game's dashboard. Alternatively, review a local recording
first and upload it later:
ravensight-playtest upload <jobId> --video
Reports and screenshots still follow the normal upload flow when video
upload is off. A persona run also uploads its step log
(transcript.jsonl: the inputs sent, what each screen showed
and the persona's notes) so the dashboard can show the evidence report,
and it is kept 90 days. This applies to projects set up before CLI
0.10.0 too. To keep it on your machine, set
"uploads": { "step_log": false } in
.ravensight/config.json or pass
--no-upload-step-log. Keep real
credentials and unrelated private content out of the test scene.
Uploaded videos use existing game-scoped access, short-lived playback
links and 90-day retention. A local-only recording does not appear in
the dashboard's Recording tab.
Capture is bounded to 15 minutes, 1280 by 720 and 200 MiB per run, within the existing 500 MiB total artifact limit. A graceful stop or crash may leave partial video; forced termination or machine loss may prevent finalization. Missing video and incomplete reports remain missing or partial. They do not become successful playthroughs.
On the job page, select each playtester's playthrough for its separate report. Open Recording for uploaded video and supported finding timestamps; Screenshots is separate. A comparison stays incomplete if either report is incomplete. Each playtester starts a fresh game process or browser session, but saved game progress and randomness may differ. Use the same build, persona, goals and reset or seed settings where supported, and treat shared findings as evidence to review, not proof of identical starting state.
Write the brief
Before the first run, a persona needs to know what your game is and what you actually want to learn. The quick brief asks for three things: your goals for the session, what would count as success, and how to get the build running, meaning the controls and how to start it.
ravensight-playtest brief
Four fields make a brief complete: at least one goal, what success looks
like, how the game is controlled, and how to start it. The brief is
versioned, so every save keeps the version before it and you can see
what changed between runs. If someone else saved a newer version while
you were editing, the CLI tells you rather than overwriting it. A job
registered with an incomplete brief is refused, except a
game-profile-only run, which does not need one. brief --show
prints the current one, --open hands you the dashboard form
instead, and --from <file> reads the fields from JSON
for an unattended setup.
Check, then run
check confirms the CLI is signed in, your token is
valid, the game is visible to it, your balance covers what you are
about to ask for, and that anything the run needs locally, such as
Godot or a browser, is where it expects. Run it any time something
seems off, and it costs nothing.
ravensight-playtest check
run is the one that spends money. It prints the price
before charging anything: how many persona runs, whether a game
profile is included, and the total against your balance. Nothing is
debited until you confirm that number, and if the price has moved
since you last checked, the CLI shows you the new one instead of
silently charging it.
ravensight-playtest run
Unless your project config or --personas names others, a run
uses one persona, fresh-eyes, a first time player. One job allows up to 100
persona/playtester runs; a comparison
counts each playtester separately. Past eight runs, the price
comes with a note about the clock: a job has 90 minutes of wall time in
total and one run can take up to 15 of them, so the later runs in a very
large job may never get to play. Nothing is lost if they do not,
because a run that did not play is refunded when the job settles; split
it into two jobs if you want everything played. Asking twice for the same
persona, or for one this game does not have, is refused before anything
is charged.
--driver chooses between the web and Godot drivers, with
--build-url or --godot-project naming the
target, --concurrency setting how many personas play at once
(two by default, while Geri and Freki comparisons run sequentially, and
check recommends a number for your machine),
and --max-actions capping one persona's turns. From CLI
0.10.0 a web or Godot run keeps a silent video on your machine by
default; --no-record-video turns it off. Video is sent
only with --upload-video. The step log (transcript.jsonl:
the inputs sent, what each observation read, the persona's notes and
the checks made on its findings) uploads by default, including for
projects set up before CLI 0.10.0, because the evidence report in the
dashboard is built from it; it is kept 90 days. To keep it on your
machine, set "uploads": { "step_log": false } in
.ravensight/config.json or pass
--no-upload-step-log.
--dry-upload prints every file and
byte that would be sent and sends nothing. --json and
--yes are the pair CI wants, since a confirmation prompt
with no terminal counts as no.
CLI 0.10.0 gives the persona a full set of inputs on web and Godot
builds: drags, right, middle and double clicks, a held mouse button,
hover, the scroll wheel, held keys that repeat, chords, timed key
sequences, and dropdowns and sliders. --phone plays a web
build on a phone sized screen (390 by 844) with touch and no mouse,
and a web game that reads a gamepad is offered a virtual one. An input
a driver does not have is refused by name and listed as a limit of the
runner, never as a finding.
After play, a web or Godot run makes edge checks and tester probes
with no model call: focus loss, resizes, rapid input, a short idle and
a reload or second start on the game's save, then, on a web build,
fast clicks, untried buttons, empty and oversized text, pause and
resume and opposite keys (a Godot game gets the four a keyboard can
make: rapid input, opposite keys, the edges and pause). A measured problem is a finding with a screenshot.
--no-edge-pass turns both off. A run then plays its
findings' recorded inputs again with no model, in a second browser or
a second Godot, and says whether each came back; --no-replay
skips it. Every report ends with what was and was not tested, kept by
the runner, and a control that was never tried is listed as not
tested, never as working.
ravensight-playtest profile is the other billed
command: it has a persona read your codebase alongside the brief,
with the same price-then-confirm step, and is priced and refunded
the same way a persona run is.
Exit codes are meant for CI. 0 is success, 1 a failure, 2 a budget exceeded with partial results written and uploaded, 3 a failed environment check, 4 a failed authentication, 5 a model error after retries, and 10 canceled. Treating 2 as a success with a warning is usually what you want.
Fix a finding
Attempt a fix on a branch
ravensight-playtest fix <jobId>/<label>
A fix is one attempt at the smallest change that removes one finding,
made on a branch in your own checkout, for $18.60. The CLI checks your
repository first, refusing a dirty tree unless you pass
--allow-dirty, then creates a branch
(--branch names your own), plans the change against actual
files, edits only those, and replays the persona that found the problem
against your edited working tree so the server can judge whether the
same failure came back. --no-verify skips that replay and
--max-actions caps the edit loop. Nothing under
addons/, .godot/ or .ravensight/
is ever edited.
It never commits and never pushes. What you get is a branch, the files it changed with their line counts, the verdict, and the exact command to open a pull request. You read the diff and decide.
Two outcomes cost nothing: a fix that concluded the right edit was no edit, and a finding that turned out to be the game working as designed. Both refund the whole $18.60 when the job settles, and the ledger names which one it was.
A fix attempt does send source to the model: the files it reads, and the edits it proposes, go through Ravensight's metered proxy, which keeps how much each call used and what it cost, never the text. What it uploads to Ravensight is the changeset summary (the branch, the changed paths with their line counts, and the verdict) and the pull request text, never the diff.
When something stops halfway
A run that was interrupted, by a sleeping machine, a crashed build or
your own Ctrl-C, is picked back up by resume. It keeps the
runs that finished, replays the rest, and never charges twice: the
registration is replayed under the job's own idempotency key, which
answers with the stored job rather than pricing a new one.
resume with no job id lists the jobs this project has a
journal for, and --status reports without restarting
anything.
ravensight-playtest resume ravensight-playtest upload <job>
upload drains whatever finished locally but did not finish
uploading. It is safe to run repeatedly, because each file is matched by
checksum and one already sent is skipped. After one online fetch the
content pack is cached and verified by hash, so a run survives the
network going away for everything except the model calls themselves;
uploads and progress reports queue and flush when the server is
reachable again.
Get a full run
A run is charged whether it covered your game or stalled on its second screen. A run comes back short for five reasons: the model budget runs out early on heavy screens, the playtester cannot read or press something, it stops before the session is over, the brief does not say how to start or which choice to make, or nobody asked for a video. Work through this list before the first paid run.
- Run
ravensight-playtest checkand fix every failed row. It is free. - In the brief, write how to start as a menu path, and name every choice on the way: the faction, character, mode or difficulty to pick. A playtester that has to guess may pick the wrong one.
- List every input and what it does, including the one that moves time on, such as End Turn or Next.
- Give three to six success criteria, one per line, each something a screen can show. With only one, the session may end when it is met.
- List known issues and anything you did on purpose, so the run does not spend actions reporting them back to you.
- Put text on every button. Give an icon or a coloured region a named node with a label inside it, and give web controls visible text or an
aria-label. - In a Godot game, add a node to the
ravensight_stategroup with a_ravensight_state()method that returns the screen, the chosen faction or character, the turn and the score. The playtester reads it with every screen, so it can confirm a choice took effect. - If the part worth testing is behind a sign-up or a long intro, add a
test_accountto the brief file, or a level select or debug start, and say so under how to start. - Ship a font that covers your game's language and set it as the project font. Text drawn as boxes is reported as a broken game.
- Keep the video. CLI 0.10.0 records one on your machine by default for a web or Godot run; pass
--upload-videoto send it too. With an older CLI, pass--record-video. - Use
--longwhen screens are heavy or the goal is far in. It doubles the actions and the time and raises the AI budget from $0.90 to $1.50, for $8.20 where a standard run is $6.40. For a set play length, use--tierand--minutesinstead.
After the run, read "What this run didn't cover" in each report before the findings. It lists where the session never got to and what the playtester could not read, press or confirm. Fix those, then run again.
While a run plays
Each persona plays your build for as long as its budget allows, then writes a report: a markdown write-up, structured findings with severities and repro steps, and the screenshots it took along the way. Those upload automatically as each run finishes, and appear on the job's page in the dashboard.
A persona plays through your own Ravensight SDK, so its session
writes real events into your events table, exactly like a player's
would, tagged synthetic. Every reader in the
dashboard, the analyst, run_sql, the rollups and your
own MCP tools excludes those rows by default, so a pack of personas
running overnight never moves your retention or your funnel numbers.
Change the Real players select on Overview, Player
insights or Events to Real + AI personas or
AI personas only when you want to look at them on purpose,
on their own or alongside real players. Those are the three pages
that carry it.
A web build driven through Playwright has no SDK of its own to play
through, so the CLI emits that session itself and needs the game's
ingest key to do it: put it in .ravensight/config.json
as ingest_key, or export
RAVENSIGHT_INGEST_KEY for the run. Without one the run
still completes and reports; it just sends no telemetry. A Godot
build talks to the SDK it already ships, which carries its own key.
To check what one run's session actually sent, open the job in the dashboard and expand Events on that run's card. Your own tools can read the same list with the CLI token, and it is never charged:
GET /api/v1/playtest/cli/jobs/<job>/runs/<run>/events
It answers up to 500 events in time order, each with its time, name,
the synthetic flag and its top-level properties, plus the
run's session id. A game server session that joined the run's
session counts as the run's too. The token needs the
playtest:read scope, and a job outside the token's games
reads as not found.
A run that never gets far enough to produce anything useful, or ends early with no findings, is not kept at its price. It is refunded in full when the cause is ours or it used no AI time, and otherwise billed at what it cost us, as "What it costs" below explains. You are billed for runs that happened, not for runs you paid to start.
One limit applies once the model has been used. An account gets 20 refunds of a persona run that used model time in any 30 days, and 5 of a game profile. Past that the unit is kept, and the job says so. Work that used no model time always comes back.
Every run the API returns says where its refund stands, in four
fields. refund_expected is true before the job settles
when the run has not earned its unit, so settling would give it back.
refund_expected_cents is the amount that would come back.
refunded is true only after the job has settled and the
credit for this run has landed on your balance.
refunded_cents is the amount credited for this run: 0
when nothing came back, and null when the run was refunded but its
price is set on the job rather than on the run.
Findings, marks, and what to remember
Open a finished job from the dashboard, or jump straight to it from the terminal:
ravensight-playtest open <job> ravensight-playtest review <job>
Each finding can be marked as you go through it: confirmed real, intended behavior, a duplicate of another finding, one you could not reproduce, wrongly rated on severity, or too vague to act on. Marking something intended offers to remember it, and remembering it turns it into a design-intent note attached to your game. The next brief a persona reads includes that note, and the next run's findings suppress the same thing again under "suppressed as intended" instead of reporting it as new.
A fix job's own page shows a Fix card above its runs: the finding it targeted, the branch, the files it changed, and the verify verdict in words. Its "Copy pull request text" button reads the same pull request body the CLI printed and copies it, so the terminal is not the only place to get it from.
Simulation Runner: mechanics and balance
Simulation Runner is a Playtest mode using the existing Ravensight API and prepaid balance. A local headless adapter runs bounded episodes with random, scripted or scored strategies. Persona playtests remain the mode for observing the screen, controls and player experience.
Run Simulation Runner on macOS or Linux, including a Linux environment under WSL. Native Windows execution is rejected before purchase because process-tree cancellation is not supported there yet. The adapter is trusted local code running with your account's permissions, not a sandbox.
One batch uses the same standard playtest_run price as one persona run (32 AI units, $6.40, paid from prepaid balance). No monthly allowance or event-meter charge replaces that payment. The CLI quotes before registration; an unproductive failed batch is refunded. Local replay is free debugging and uploads no new server report.
ravensight-playtest simulate --config simulation.json --driver-config bridge.json
ravensight-playtest simulate --resume path/to/state.json
ravensight-playtest simulation-replay path/to/trace.json --driver-config bridge.json
Example simulation.json:
{
"version": 1,
"seed": "balance-2026",
"runs": 1000,
"max_steps": 100,
"workers": 4,
"strategies": [
{ "name": "random", "policy": "random" },
{ "name": "aggressive", "policy": "scored" },
{ "name": "opening", "policy": "scripted", "actions": ["buy", "end-turn"] }
]
}
Use the existing cli_stdio bridge configuration to launch your own game process. The example paths below are local placeholders. You may instead set driver_config in the simulation file to a path relative to that file.
{
"command": "/absolute/path/to/game",
"args": ["--headless"],
"cwd": "/absolute/project"
}
The engine-agnostic adapter exchanges newline-delimited JSON over standard input/output. Implement simulation.start and simulation.step, expose legal actions and game-defined action scores for scored strategies, and return a state_hash for replay comparison. Scripted action lists stay local. A seed alone cannot guarantee identical results: your adapter must seed its own randomness and control nondeterministic state. See the Playtest CLI installation guide; use the matching CLI protocol and adapter examples before running a paid batch.
Each protocol message is one JSON line. The runner supplies an episode seed and strategy name. A minimal exchange looks like this (your adapter supplies the actual state hashes):
{"jsonrpc":"2.0","id":1,"method":"simulation.start","params":{"version":1,"seed":"episode-seed","strategy":"aggressive","max_steps":100}}
{"jsonrpc":"2.0","id":1,"result":{"done":false,"state_hash":"state-0","actions":[{"id":"buy","scores":{"aggressive":3}},{"id":"end-turn","scores":{"aggressive":1}}],"metrics":{"coins":4}}}
{"jsonrpc":"2.0","id":2,"method":"simulation.step","params":{"action":"buy"}}
{"jsonrpc":"2.0","id":2,"result":{"done":true,"state_hash":"state-1","actions":[],"outcome":"win","metrics":{"coins":2}}}
Strategy names use lowercase slugs of up to 64 characters (letters, digits, underscores and hyphens, starting with a letter). Metric values must be finite and between −1015 and 1015. Only terminal, completed episodes contribute outcomes and final metrics. Keep standard output for protocol messages and send diagnostics to standard error. The CLI includes a runnable examples/simulation/economy.mjs adapter. Use your game rules and legal actions in its place; this protocol does not simulate a game from a design document by itself.
A batch allows up to 10,000 episodes, 10,000 steps per episode, 16 workers and 16 strategies, additionally bounded by one million total actions and 15 minutes. At most 10 selected traces stay local for replay. A probe initializes the protocol only; it does not run a free batch. Resume uses the existing paid job rather than registering a second batch.
Replay checks captured state hashes, completion flags, outcomes and metrics. fully_replayed: true means the complete recorded window matched, which may still end at a step limit rather than a terminal game. A size-capped or failed trace can instead report matched_prefix: true with fully_replayed: false. When a failed action was captured, replay retries it; failure_reproduced: true requires the same sanitized protocol error. A successful retry is a divergence, not a reproduced failure. An initial-start failure has no prefix to verify, and an exhausted or illegal strategy can verify only its captured prefix.
The Playtest job page shows requested, completed, failed and truncated counts, total steps, outcomes per strategy, and metric count/minimum/maximum/mean. Metric names and units come from your game. A truncated episode reached a limit and must not be read as a completed win or loss. Comparing strategies can suggest questions to investigate; it does not establish that an exploit exists or automatically recommend a balanced design.
Only bounded summaries are sent to Playtest: sanitized strategy names/policies, seed, config hash, counts and metrics. Local commands, paths, action scripts and raw per-tick state are not uploaded as simulation summaries. This evidence stays separate from real-player analytics. Your agent can find it with list_playtest_jobs and read it with get_playtest_report; it is not automatically promoted into studio findings or memory.
Hosted Linux simulations
Upload a Linux x86_64 headless ZIP from Playtest, wait for validation, then request and accept a price quote. Hosted runs use a repeatable random strategy and return a simulation report. This mode does not include graphical gameplay, Geri or Freki runs, video recording, or human player feedback.
Qualify once with $10 in verified prepaid funding on the studio owner's account. Confirmed prepaid payments totaling $10 qualify the account. This is usable credit, not a setup fee or an extra charge. After qualifying, you can spend the credit down below $10; each new hosted request needs the start balance on its quote (see Starting a Labs job), and only the amount due is charged. If funds are short, the owner can choose Add funds in Billing, then return to Playtest and refresh. Included monthly AI units do not pay for hosted runs. A valid paid build deposit from before this rollout remains usable for that build's first run when its remaining quote is covered; new uploads and later runs still need the initial verified funding.
Uploading reserves $0.49 from that balance for the build's first hosted run. The quote shows one total, the Playtest cost, then any build deposit already held and the remaining amount due. The held deposit is credited once toward that first run, so it is not a second fee. For the current standard $6.09 quote, a held $0.49 deposit leaves $5.60 due. A later run has its own full quote; always review the amount shown before confirming.
Known never-started runs, hosted-service failures and customer-build failures refund hosted compute. Cancellation after confirmed execution start retains the $0.49 compute charge. The Playtest portion follows its existing refund policy. An unused build deposit is returned after the build is deleted or expires and safe cleanup is confirmed; pending or unknown work must be reconciled before a refund is final.
The time limit. A hosted run or comparison that reaches its time limit is refunded in full, machine and comparison charge alike. The quote states this before you accept, and a purchase keeps the terms it was accepted under.
A busy service does not refuse paid work. An accepted run is charged, waits in line for a machine, oldest first, with its place and expected start on the run, and starts on its own; a run that never gets a machine within six hours, or is canceled or loses its build while it waits, is refunded in full. Funding does not bypass upload limits: an exhausted allowance requires waiting for the stated limit to clear, not another payment. You can still view existing runs, request cancellation and delete builds when new work is blocked. Only studio owners and administrators can submit hosted work; funding uses the owner's billing account.
The initial hosted release permits one active run and ten new run admissions per UTC day across the service. Validation is limited to two attempts per studio and ten across the service per UTC day. Upload grants are also bounded: eight grants or 512 MiB per studio, within 64 grants or 4 GiB across the service. Upload allowances are cumulative and do not reset daily; deletion does not replenish them.
How a persona plays your build
For a web build, a persona plays through a driver built on Playwright: it sees the running page, clicks and types the same way a person would, and reads back whatever your game reports.
For a Godot project, the CLI copies your project into a temporary
directory, injects a driver addon into that copy only, and launches
it there. Your project on disk is never modified. If you implement
_ravensight_state() on a node in the
ravensight_state group, the driver reads it too, so a
finding can cite the exact level, menu, or scene your persona was
looking at. See "Playtest mode" in the Godot SDK guide for the
details.
The addon only ever activates deliberately. It needs a flag on the command line or an environment variable, it binds to localhost and nothing else, it demands a per-run token before it will answer any other call, it takes one client at a time, and it frees itself the moment any of that fails. A release export does not contain it unless the preset asks for it by feature tag.
Do not run a persona UI playtest of a Godot game headless. Headless Godot routes no synthesized mouse or GUI input, so a click on a button does nothing and nothing takes keyboard focus. That makes headless a smoke test mode rather than a playtest mode for anything with a user interface. The Simulation Runner above instead calls your explicit mechanics adapter and does not synthesize GUI input. On a machine with no display, run a windowed Godot under a virtual framebuffer such as Xvfb instead. The CLI prints this in the run's console log when it launches headless.
Video from the Godot driver is a sequence of frames rather than a container, so stitching it into one file needs ffmpeg, and ffmpeg stays optional.
What leaves your machine
Your build is never uploaded, and a persona run never sends your source code. The prompts a persona reads, including your brief, and what it observes while playing transit Ravensight on the way to the model provider named on the subprocessors page, metered but not kept. A game profile or a fix attempt also sends the source files it reads, the same way and equally not kept. Your art and audio files never leave at all: see Your own art and audio for exactly what a feature sends about them. What uploads to Ravensight is exactly the reports, screenshots, and bookkeeping named on a fixed allowlist, nothing else. The dashboard's What leaves your machine page lists that allowlist against the code that enforces it, so it never drifts out of date with what actually ships.
Retention
Reports, findings, marks, and briefs are kept for as long as the game exists. Session video, which is opt-in, and a persona run's step log are kept for 90 days and then dropped.
What it costs
Playtest spends from your prepaid balance, the same one as everything else on this page. Each persona run is currently $6.40, a long persona run is currently $8.20, a game profile is currently $8.40, and a fix attempt is currently $18.60. Each price covers everything the work can cost at its limits, from the models to storing and serving its screenshots, video and reports, doubled, plus a margin of at least a dollar, and the quote shows it as one total. The price is charged when a job registers and refunded, up to the limit below, for any run that never produced a report, or that ended early (out of budget, out of time, an error, or stuck behind a blocker) with no findings, so what you keep paying for is what you actually got. A run that played to the end and found nothing is a clean pass and is charged.
A thin run is billed at what it cost us. When a persona run ends with fewer than 15 actions and the game is not the reason (the AI budget ran out, the playtester met a tool or driver limit, or it stopped early with nothing blocking it), you are charged only what the run cost us to run: its AI spend and its storage and transfer, rounded up to the cent. The rest of the price is refunded when the job finishes, and the run says why it was thin and what to try next. A run the game itself cut short, such as a blocker the persona reported with evidence or a persona that quit in character, is charged in full, because that run did its job. So is a finished tiny game: when the persona reaches the goal in a few actions and the run's report confirms the goal was met, you got what you asked for.
A run that did not earn its price is billed the same way when it still used AI time: a run of fewer than five actions, a run that ended early and found nothing, or a run that failed on the game's side and still left a report. You are charged what it cost us and the rest is refunded, with the reason on the run. It still comes back in full when the cause is ours: a failure of the AI provider or of our service that our servers recorded on the run, one of our own limits stopping the run before any play, or no report produced. A run that stops on an error on your machine, such as a driver or tool failure, is billed at what it cost us like any other run that did not earn its price. A run that used no AI time also comes back in full. An account gets 20 runs billed at cost in 30 days, counting both kinds; past that a run is kept at its price and says so.
A long run, ravensight-playtest run --long, is for a game
whose first screen is heavy. It gets $1.50 of AI budget where a
standard run gets $0.90, twice the actions and twice the wall clock,
for $8.20 where a standard run is $6.40, and the price is quoted and
confirmed exactly like a standard one. check on a web build measures the first screen and
suggests --long with both prices when it is heavy; it
never charges anything.
A local run can also play on one of the cloud tiers' allowances:
ravensight-playtest run --tier medium --minutes 30 gives
every persona the Medium tier's model budget and action count for
thirty minutes, on your own machine. Each tier has its own shortest
length (Jam 5, Small 8, Medium 15, Large 30 minutes) and a local run
may go up to 240. The price is quoted and confirmed like any other,
for example $5.60 for Jam at 5 minutes and $16.20 for Medium at 30.
--focus and --avoid give every persona goals
to put first and things to stay out of, and --start opens
a web build at a query or hash.
A fix attempt includes the persona replay that verifies it, and is refunded in full when the fix changed nothing, the finding turned out to be design intent, or the game did not boot for the verify replay (up to twice in any 30 days per account, with CLI 0.6.0 or later, which is what reports it).
An account gets 5 refunds in any 30 days of a fix attempt that used model time, and a cancel or any other failure counts the same as those answers. Past that the attempt is kept and the job says so. An attempt that used no model time always comes back.
Or fix it with your own agent over MCP
If you would rather your own coding agent make the change than run a
fix attempt, it can read the same findings. With
an MCP token (see Analytics MCP), your own coding
agent can find the job with list_playtest_jobs, list its
findings with list_playtest_findings, read the full
report with get_playtest_report, then edit the code and
open a pull request itself, exactly as it would for any other
change. Ravensight never writes to your repository: those three
tools are read-only, and everything from there is your agent working
in your own checkout with your own tools.
Starting a Labs job
Fix v2, Validate changes, Build a feature, Create a game and hosted runs each ask two things of an account before anything is charged.
- At least $10 of top-ups over the account's lifetime. A promotional balance does not count, and spending the money does not undo it. Without it, a fix runs as an ordinary fix.
- A start balance: the price of the whole plan plus 25 percent, at least $2 extra, rounded up to a whole dollar. A $18.60 Fix v2 needs $24.00, and Validate changes at three runs a side, $52.80, needs $66.00.
Only the price is charged. The extra stays in your balance, so a refund that lands when the job settles does not leave you stranded before you can try again. The CLI and hosted quotes show the figure before you confirm. An ordinary persona run, game profile or fix starts on its price alone.
Create a game (Labs, Experimental)
Create a game starts a small playable 2D Godot prototype from a brief, on your own machine. It is Experimental: it may not produce a game you want, so read the design before you approve it and read the code before you ship it. It is off until the platform switches it on, and only an owner or admin can start one. Ravensight never holds or writes your source, and nothing is pushed.
npx ravensight-playtest create "A keeper walks a dark hall and lights each lamp in turn" --name "Lantern Sweep" --milestones 3 --size medium
# read the design and approve it on the plan's page, then, from the project folder:
npx ravensight-playtest create <job-id>
What it costs. You declare how many milestones to buy and the largest size each may be. The account must have added at least $10 in top-ups, the balance has to reach the plan's start balance (see Starting a Labs job), and the CLI shows both before you confirm. Part of it is charged at the start, for the design, the scaffold and one persona run. Each milestone is then an ordinary Build a feature job, charged when it starts, with that feature's own refund rules. The balance is checked, not held, so a milestone your balance can no longer cover stops there. The Labs page states the current price.
The design. The first command makes a new game, with its key in a file git ignores, and writes a game design with a milestone list, core loop first. It is saved among your design documents. A person approves or rejects it on the plan's page. Rejecting it gives the whole charge back, and so does a brief the model declines, within the refund limit below. There is no editor: to change a design, reject it and start again from a better brief.
The scaffold. A Godot 4 2D project with the public Ravensight SDK
unmodified, a key loader, a player opt-out in its settings, build-time key injection
for a public build, events that always set rs_kind, and a
_ravensight_state() node a playtest reads. It is checked in Godot to
import and start before the charge for it is kept. Every visual is a placeholder
primitive. Studios bring their own art and audio: nothing is generated. The first
command says where the files go in the new project, assets or the
folder you name with --assets-dir. Put them there before you carry on,
and each milestone can use them, as in
Your own art and audio.
Milestones. One at a time, each on its own branch, landing on
main when its test scenarios pass. The next is bought only when the last
validated, and the run stops at the count you declared, whatever the design lists. A
milestone that does not validate stops the run: its branch holds the attempt, and
running the command again tries it once more, which uses up another declared
milestone if the attempt kept its charge.
Playable. When every declared milestone has validated, a persona plays the finished game. It reads as playable when Ravensight's own records show that run finished cleanly and the game itself reports at least one completed core loop. A persona is a model playing the game, not a player, so play it yourself before you ship it.
Stopping. Ctrl-C, or create <job-id> --stop,
closes the plan. What finished stays paid for, and what never started comes back: the
in-flight milestone by its own rules, the persona run if it was never played. A
milestone that never started was never charged. If the process dies instead, the same
command carries on, and a plan left alone closes after 14 days.
The refund limit. Once the model has been used on a plan, an account can get its first charge back twice in any 30 days. Past that, a brief that is declined, a design you reject and a plan that stops before its scaffold boots all keep that charge, and the plan's page says so. The persona run that never played still comes back. The CLI states how many you have left before you confirm.
The hourly limit. A studio has an hourly limit on model spend, and a large milestone's budget can pass it. The job pauses until the top of the next hour, says how long, and carries on. A pause costs no model time and Ctrl-C ends it. It does count toward the run's own time limit, so a run that passes that limit while it waits stops there, and that job's refund rules apply.
Build a feature (Labs beta)
Build a feature turns a short brief into a specification a person approves, then builds it on a new branch on your own machine and checks it against that specification. It is for 2D Godot projects and one bounded gameplay system or a few of them: movement, health, stamina, inventory, scoring, simple enemy behaviour or a HUD widget. It is off until the platform switches it on and an owner or admin turns on Labs for the game on the Labs page. Ravensight never holds or writes your source: the server stores paths and line counts.
npx ravensight-playtest feature "Hold shift to sprint, draining stamina that refills at rest"
# read, edit and approve it on the Labs page, then:
npx ravensight-playtest feature <spec-id> --godot-project .
The specification. It lists requirements, acceptance criteria, affected systems, proposed files, the SDK events to add and up to three test scenarios, and it is saved as a brief among your design documents, so Huginn, the AI analyst, and the partner can read it. Writing one is one AI unit, which the included monthly allowance can cover. A brief bigger than the large size, outside those systems or needing 3D is declined and costs nothing. Only a person can approve a specification, in the dashboard, and an edit takes the approval away.
What it costs. A job needs an account that has added at least $10 in top-ups, and a balance at the plan's start balance (see Starting a Labs job). The plan is a price set by the specification's size, plus one persona run for each test scenario. The CLI shows both before you confirm, it is charged once from your prepaid balance, never from the included allowance, and an empty balance is refused before anything starts, with nothing charged.
What it does. On a clean working tree, it checks that the
project starts, then plans, edits at most 40 files, runs the named checks (import,
script check, the three asset checks and, if you allow them, your own tests) and has a persona play each
test scenario. A failed check or a failed scenario starts a repair, at most two.
The approved specification is frozen on the job, so nothing during the job can
change what counts as done. It never commits or pushes unless you pass
--open-pr and say yes at the prompt, and that only happens for a
verified feature.
What you get back. If nothing changed, or the change does not pass its checks, the whole job is refunded, up to three times in any 30 days per account for a job that had already used model time. Past that the feature's own price is kept, the job says so, and unplayed scenario runs still come back. A job that used no model time is always refunded. Once a change is delivered the unit is kept, verified or not, and the report says which. Verified means Ravensight's own records show that every scenario's persona run finished with an accepted report, logged no script errors and filed no blocker or major finding. A scenario run that did not earn its unit is refunded on its own. These are model players, not real ones, so play it yourself before you ship it.
Godot 3D proof of concept (Labs, Alpha)
Labs beta is Godot 2D. The Alpha is one small 3D template for trying Build a feature and Validate changes on a 3D project, and nothing more. Create a game does not make a 3D game from a brief, and refuses to try. How well a model builds 3D has not been measured. It has no switch and no price of its own: the same Labs opt-in applies, and the jobs cost what they cost on a 2D project.
npx ravensight-playtest template godot-3d --game <game-id> --dir beacon-walk
cd beacon-walk
npx ravensight-playtest feature "Each beacon is worth two points" --alpha-3d
# read, edit and approve it on the Labs page, then:
npx ravensight-playtest feature <spec-id> --alpha-3d
npx ravensight-playtest validate <branch> --base main --alpha-3d
The template is placeholder meshes with the public SDK and no key, and writing it costs
nothing. Without --alpha-3d, both commands refuse a 3D project for free.
A persona plays with keys and input actions and can click a node by its path, but it
cannot steer a camera with the mouse, so a feature that needs mouse look cannot be
played by a persona. Your own models are listed by type and size and are never sent to
the model.
Your own art and audio (Labs beta)
Ravensight does not make art or audio. You supply the files, they stay in your
project, and using them has no separate price: it is part of the
Build a feature unit. Put them in a folder inside the
project, assets unless you name another with
--assets-dir, and see what is there:
npx ravensight-playtest assets
npx ravensight-playtest assets --assets-dir art --grid 32
This runs on your machine. It needs no login, costs nothing and sends nothing. It lists every file by type and size. For a PNG it adds the dimensions, transparency, measured pixel pitch and a guess at the layout: one picture, a tile, a strip or a sheet. For WAV and Ogg it adds the format and the length. Other formats are listed by type and size only.
The warnings say what will go wrong in the game.
- The real pixel pitch is measured from the pixels. A file described as a 32 grid can be 100 or more art pixels across, and
--gridwarns when it differs from what you expected. - Faint, nearly invisible pixels can reach the edge of the canvas, so threshold alpha before trimming. The warning gives the box both ways.
- A tile with its own frame draws a grid across the floor. Use tiles with no per-tile frame, or one seamless texture.
- Godot does not import Opus in an Ogg file, compressed WAV, or WAV saved with the extended header.
- Pixel art blurs when the project's default filter is smooth, unless the node drawing it sets the nearest filter.
During a feature job. The model reads that list and uses the
files by their res:// paths. It cannot read, search or write an art or
audio file, or write anything else in the declared folder except the
.import settings beside a file. Anything the feature needs that you
have not supplied stays a placeholder primitive, such as a
ColorRect or a Label, and is named in the report. Nothing is
generated.
Three more checks. asset_references checks that every
asset the change names exists, with that exact case, inside the project.
asset_import imports the project in Godot and reads what it made for
each of them. pixel_art_settings checks that pixel art the change names
has the nearest filter and clean import settings. Only what the change names can
fail a job. A reference that does not resolve or a file that does not import starts
a repair, and after the repairs blocks the change, so the whole job is refunded. A
pixel art setting that stays wrong starts a repair too, and is then listed as a
remaining risk.
What you get back. The report says how many files the change wired
in, how many the project uses and how many are unused, and names the placeholders
left for you to supply. Which files is in assets-report.md in the run
directory, on your machine.
Exactly what leaves your machine.
| What | Where it goes |
|---|---|
| The content of an art or audio file | Nowhere. Not to Ravensight, and not to the model. |
The assets command's output | Nowhere. It prints on your machine. |
| Each file's path, type, size, measurements and warnings, during a feature job | To the model, through the proxy, which does not store it. |
| How many files, how many wired in, used and unused, how many of each kind of warning, and each asset check's name and result | Uploaded in the feature's report. This part names no asset file. |
| Placeholders left to supply | Uploaded by name, because they are what you are being asked to supply. |
| The pull request text | Uploaded in the report. The model writes it, so it may name a file the change used. Read it before you merge. |
assets-report.md and assets.json, which list every file | Nowhere. They stay in the run directory, because they are not on the upload allowlist. |
Getting help
Report an issue with the CLI, or ask anything else, at support@realityse.com.