Playtest Notes

A Playtest Note sends useful context made by the running game to your agent.

The context is the important part. It can be a level you built, choices you made, corrected artwork, game data, logs, or another file. You can add a message, but the message is optional.

Use Update when you only want to tell the agent what to change. Use a Playtest Note when the game has custom data or a file that the agent needs.

Examples

Send a level you built

Your game has a level editor. You build a level and press Save for agent.

The game sends the level as JSON. You can add a message such as "Use this as level 3." The agent adds the saved level to the next version of the game.

Vote on asset variations

Your agent makes several versions of an asset. The game shows them together so you can vote each one up or down.

The game sends the asset references, your votes, and any optional messages. The agent uses those choices when making the next version.

Fix a spritesheet

The frames in a spritesheet do not line up. The game gives you a small editor where you can move frames or fix pixels.

When you finish, the game sends the corrected spritesheet and its frame data. The agent replaces the old artwork and integrates your corrected version.

For Creators

The game should give you a tool made for the job, such as:

• Save level for agent
• Submit asset votes
• Send corrected spritesheet

It should not make you copy the result into a message. The game already knows the level data, votes, artwork, or other context, so it sends that context for you.

Only the creator can see these controls. Players cannot use them.

When you start an update, choose the saved context you want the agent to use. You can choose several items from the same playtest session.

Use Tweaks when you only need to change a setting such as speed, color, or difficulty.

For Agents Building the Game

Use the PlayDrop plugin's playtest-notes skill.

Build a small, purpose-made creator tool. Do not add a generic message box and call it Playtest Notes. The runtime must send useful custom context, and a creator message should be optional.

Only show the tool when sdk.creator exists. For example, a level editor can send its saved level as JSON:

const creator = sdk.creator;
if (!creator) throw new Error("creator_tools_unavailable");

await creator.notes.add({
  kind: "JSON",
  fileName: "level-3.json",
  value: {
    type: "level-editor-export",
    schemaVersion: 1,
    level: levelEditor.export(),
    message: optionalMessage || undefined,
  },
});

Use the typed note kind that matches the runtime context:

• JSON for levels, votes, selections, alignment data, and other structured results
• IMAGE for corrected spritesheets or other edited images
• ASSET for an exact PlayDrop asset reference and integration comment
• LOG for runtime diagnostics
• MARKDOWN for longer structured text
• TEXT only when plain text is itself the useful result

Kinds use uppercase names. Notes do not have a title field. Use the SDK types so mistakes cause a clear error.

For Agents Updating the Game

The runtime context is the main input. An optional creator message only helps explain it.

PlayDrop tasks already include the context chosen by the creator. Inspect every selected JSON file, image, log, or asset reference. Check which game version produced it, then integrate the result into the game source and test the new version.

If you are working outside a PlayDrop task, read the saved context with:

playdrop notes browse app:creator/game@1.2.3 --json

Use --output <directory> when you need the attached files.

After the update is finished and tested, clear only the items you used:

playdrop notes clear app:creator/game@1.2.3 42 43

Do not clear context you did not inspect or integrate.

Learn More

• Creator Tools
• Tweaks