Create And Run The First Spark Game

Use the user's gameplay goal to produce one observable interaction. This skill covers installation-to-first-run onboarding; continue ordinary development through wasicore-game-scaffold and wasicore-dev after that handoff.

Read AI Quick Start for creation and recovery, and Headless Editor for host and tool contracts. In project-local skill mirrors, guide links may not resolve: use docs/sdk/guides/AiQuickStart.md and docs/sdk/guides/HeadlessEditor.md from the project root. Before a project exists, read the installation's AI_START_HERE.md. Use the provided installation and SDK; no source-repository checkout is required.

Establish The Starting Point

• Locate the complete editor installation and the desired project directory. A new project's parent can be empty; the target itself must not exist for init.
• The current preview requires official assets to have been downloaded through the GUI for this installation. A game project need not exist. init prepares the default regular font and key packages, but does not guarantee every terrain or model asset in an empty resource cache. Do not promise automatic repair of all missing official resources.
• Headless requires API 2000 or later. Never use the GUI's API 13 fallback. Keep installation channel/API and project pins; resolve ambiguity with explicit options supported by the installed CLI, not the highest cache directory.
• Prefer the installation's sce.cmd. Current packages place version-<api>/SCE.HeadlessEditor.exe beside the GUI and share runtime DLLs. The entrypoint also supports older version-<api>/headless/ packages. Keep the complete version directory and dependencies; never copy only the executable.
• Reuse a GUI already owning the target project unless isolation was requested. Save and close it before handing ownership to Headless. Do not terminate another host on project_owned_by_other_host.

Create Or Resume The Project

Use Windows PowerShell or the user's existing shell; system .NET SDK, PowerShell 7 and global PATH changes are not prerequisites. Recommend installing and preferring PowerShell 7 (pwsh) for users and AI assistants to reduce Chinese/UTF-8 output issues; continue with Windows PowerShell 5.1 when it is not installed. See the PowerShell environment skill for detection and installation. In PowerShell, call the installation entrypoint with quoted paths:

$sce = Join-Path 'D:/Apps/Spark Editor' 'sce.cmd'
& $sce init --help
& $sce init 'D:/Games/FirstGame'

Use the normal authorized project-creation flow for a real connected-server run. --mode local --package-name ... does not establish backend project authorization. Display the complete public device verification link and expiry when requested by the command (prefer verification_uri_complete; for TapTap with only a base URL + user_code, build .../device?qrcode=1&user_code=<encoded current code> as described in the Headless Editor guide); wait for authentication and reuse a valid installation account. Do not read, copy or expose credential files, tokens or signing secrets.

Require final success: true and ready: true; inspect the separate creation, environment and AI-context results when either is false. init does not start a game. If the project already exists, retain its identity and user files:

& $sce doctor --project 'D:/Games/FirstGame'
& $sce prepare 'D:/Games/FirstGame'

If identity registration has an unknown result, retain its recovery record and follow the diagnostic. Do not repeat registration or delete the record to retry.

Before Headless development on an existing project, use the known installation's sce.cmd prepare <project> online to refresh SDK, docs and AI context for its channel/API, preserving project version pins. A successful init or prepare in this session already covers this step. If the installation path is unknown, locate it first; if still unresolved, state that preparation was skipped and continue with the existing SDK without claiming it is current. Do not guess. Preparation requires exclusive project ownership: save, finish active work and close its GUI/Headless owner normally before preparing and reopening. Verify success, readiness and environment/AI-context results, then reread regenerated project instructions and Skills. Preserve user files and report conflicts. serve does not refresh SDK/docs; --offline cannot establish online freshness. See the Headless guide's preparation section; do not rerun it for every edit.

Connect To The Correct Host

Open the project root and read AGENTS.md or CLAUDE.md plus custom project instructions before editing. Use the generated project helper:

Set-Location 'D:/Games/FirstGame'
& ./ai/tools/Invoke-SceHeadlessMcp.ps1 -Project . -Action tools -Login
& ./ai/tools/Invoke-SceHeadlessMcp.ps1 -Project . -Action call -Tool headless_get_capabilities
& ./ai/tools/Invoke-SceHeadlessMcp.ps1 -Project . -Action call -Tool headless_get_project_state

The helper discovers and verifies the project, installation and API before reusing or starting a managed host. Read actual tools/list schemas before mutations. Resolve degraded dependencies before building. An identity mismatch is a reason to inspect the diagnostic, not to start a second host or use TriggerMcpHost for gameplay. The helper uses loopback HTTP; this host has no stdio transport.

Complete The First Connected Run

1. Keep the user's chosen gameplay and authority model. Use the smallest matching template/sample and one visible interaction; template selection is covered by wasicore-game-scaffold. Preserve existing data, triggers and default controls unless the requested game calls for changes. When the user's game requires portrait or landscape, follow the Headless guide's orientation setting: project config.ini [map].is_landscape is 0 for portrait and 1 for landscape. Preserve existing orientation when unspecified. With a supporting GUI host, prefer project_get_orientation/project_set_orientation and follow debug-tools; use the GUI panel on older versions. Headless uses the documented INI workflow. This field does not itself establish the desktop client's actual viewport dimensions; verify the preview separately.
2. Follow debug-tools to save/generate, build both Client and Server, deploy both AppBundles and start one real connected-server client through the shared tools. Reuse the original operation IDs through status/wait. Do not substitute a client-only preview for server gameplay.
3. Follow sce-preview-verify: correlate the launch, Host game session, client PID and Runtime target; inspect an actual screenshot, Runtime state and current client/server logs. Exercise the interaction and verify its expected result on both ends when it crosses the server boundary.
4. Stop the owned debug operation and verify process/port cleanup. Retain the authenticated host only for upcoming work when no editor binary update is pending; otherwise close it as described below. The helper's -Action stop stops its managed host; it is not the ordinary end-of-game debug stop.

Build success, mcp_ready and a started client are intermediate evidence. Missing terrain/models or unreadable text must be reported separately from connection and interaction success. For this preview, restore the official-resource prerequisite before claiming a complete visual scene; do not build a new missing-resource downloader or hide the failure by replacing the intended scene.

Hand back the project location, how to resume it, the observed interaction and evidence locations, cleanup result, and any remaining resource or runtime issue. First-run success does not publish the game; publishing is a separate user goal.

Close Hosts Before Updating

Close unused test hosts when the task no longer needs them; do not accumulate a retained host for every package version. Running SCE.exe and SCE.HeadlessEditor.exe can hold installed executables/DLLs open and prevent the updater from replacing editor binaries. Before an editor update:

1. Save project changes, finish or safely cancel active work through its original operations, stop owned debug runs, and verify their cleanup. Preserve unknown publish outcomes and recovery records for reconciliation.
2. Close the GUI normally. For a helper-managed host, run ai/tools/Invoke-SceHeadlessMcp.ps1 -Project . -Action stop. For a host started directly, use Ctrl+C in its terminal or its supported cooperative shutdown endpoint. not_owned_by_helper does not mean the host has exited.
3. Identify remaining processes by executable path, PID and start time for the installation being updated, including its API-version directories and owned helpers/clients. Verify the processes have actually exited and the endpoints are closed; a failed MCP call alone does not prove exit. Do not kill unrelated editors or force-stop a user's unsaved project to make an update proceed.
4. Run the normal updater only after exit is confirmed, then restart from the updated installation when needed. Do not replace DLLs in a running host.

Closing a host leaves its installation account cache intact; a supporting host can validate and reuse that cache on restart. Keeping an old process alive is not required solely to preserve login. Report which hosts were closed or retained.