Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion URL-POLICY.md
Original file line number Diff line number Diff line change
Expand Up @@ -86,7 +86,7 @@ These top-level paths are canonical. They do not move.
| `/migration/*` | Coming from another engine |
| `/desktop/*` | Desktop application specifics |
| `/mcp/*` | MCP server, CLI, per-harness setup |
| `/api-reference/*` | Crafty SDK and public APIs |
| `/api-reference/*` | Summer SDK and public APIs |
| `/guides/*` | Task-oriented how-to |
| `/publishing/*` | Export and ship |
| `/knowledge-base/*` | Question-shaped pages, answered directly |
Expand Down
89 changes: 0 additions & 89 deletions api-reference/crafty-sdk/crafty.mdx

This file was deleted.

69 changes: 36 additions & 33 deletions api-reference/crafty-sdk.mdx → api-reference/summer-sdk.mdx
Original file line number Diff line number Diff line change
@@ -1,18 +1,18 @@
---
title: "Creating Games on Crafty"
description: "Crafty is a powerful platform layer that provides multiplayer, persistence, and economy features. You bring the game, we bring the infrastructure."
title: "Creating Games on Summercraft"
description: "Summercraft is a powerful platform layer that provides multiplayer, persistence, and economy features. You bring the game, we bring the infrastructure."
icon: "gamepad-2"
---

## Introduction to Crafty
## Introduction to Summercraft

Crafty is a place where you can play games made by the community in Summer Engine. It's a platform made to make it easy for developers to make and share their games without having to go through store experiences made +20 years ago. The Crafty SDK works similar to Steams steamworks, and aims to make it more easy to build and share your games. Rather than forcing you into a rigid template or specific game type, Crafty seamlessly integrates with your project to provide robust multiplayer infrastructure and backend services.
Summercraft is a place where you can play games made by the community in Summer Engine. It's a platform made to make it easy for developers to make and share their games without having to go through store experiences made +20 years ago. The Summer SDK works similar to Steams steamworks, and aims to make it more easy to build and share your games. Rather than forcing you into a rigid template or specific game type, Summercraft seamlessly integrates with your project to provide robust multiplayer infrastructure and backend services.

The mental model is simple: you build your game's unique design and systems, and plug in the Crafty SDK to handle all the complex platform features.
The mental model is simple: you build your game's unique design and systems, and plug in the Summer SDK to handle all the complex platform features.

## What Crafty Handles
## What Summercraft Handles

The Crafty SDK provides out-of-the-box support for:
The Summer SDK provides out-of-the-box support for:

- **Multiplayer Runtime:** Server-authoritative networking and matchmaking infrastructure.
- **Player Management:** Unified player identity and session handling.
Expand All @@ -22,7 +22,7 @@ The Crafty SDK provides out-of-the-box support for:

## What You Build

Because Crafty manages the heavy lifting on the backend, you're free to focus purely on making a great game:
Because Summercraft manages the heavy lifting on the backend, you're free to focus purely on making a great game:

- **Core Gameplay:** Your unique mechanics, controls, and game loops.
- **Worlds & Scenes:** Environments, levels, and visual rendering.
Expand All @@ -33,83 +33,86 @@ Because Crafty manages the heavy lifting on the backend, you're free to focus pu

The minimum integration contract:

1. `extends CraftyGame`
1. `extends SummerGame`
2. implement lifecycle hooks (`_game_init`, `_game_start`, `_game_end`, `_player_joined`, `_player_left`)
3. use player synced state (`set_synced` / `get_synced`)
4. keep authority on server paths (`Crafty.is_server()`)
4. keep authority on server paths (`Summer.is_server()`)
5. provide valid `manifest.json` and export/upload flow.

## Templates Are Optional

Templates are examples, not requirements.

- `CraftyCharacter3D` is the optional 3D character template path.
- For 2D/RTS/card/turn-based games, extend `CraftyPlayer` directly and sync your own game model.
- `SummerCharacter3D` is the optional 3D character template path.
- For 2D/RTS/card/turn-based games, extend `SummerPlayer` directly and sync your own game model.

## Recommended Reading Order (Fresh AI / Fresh Dev)

1. `CraftyGame` and `Crafty` basics
2. `CraftyPlayer` contract and `set_synced`
1. `SummerGame` and `Summer` basics
2. `SummerPlayer` contract and `set_synced`
3. subsystem modules you need (`data`, `economy`, `teams`, `score`)
4. local test runner flow
5. export/upload and banned API constraints.

## API Sections

<CardGroup cols={2}>
<Card title="Crafty Singleton" icon="box" href="/api-reference/crafty-sdk/crafty">
<Card title="Summer SDK Naming" icon="arrow-right-left" href="/api-reference/summer-sdk/naming">
Migrating from Crafty: every renamed class, autoload, manifest key, and path
</Card>
<Card title="Summer Singleton" icon="box" href="/api-reference/summer-sdk/summer">
Match control, player queries, spawning, server/client checks, subsystem access
</Card>
<Card title="CraftyGame" icon="workflow" href="/api-reference/crafty-sdk/crafty-game">
<Card title="SummerGame" icon="workflow" href="/api-reference/summer-sdk/summer-game">
Required base class, lifecycle hooks, and practical game structure
</Card>
<Card title="CraftyPlayer" icon="user" href="/api-reference/crafty-sdk/crafty-player">
<Card title="SummerPlayer" icon="user" href="/api-reference/summer-sdk/summer-player">
Minimal player contract: identity, synced vars, input, and optional 3D template path
</Card>
<Card title="Subsystems & Signals" icon="radio" href="/api-reference/crafty-sdk/subsystems-signals">
<Card title="Subsystems & Signals" icon="radio" href="/api-reference/summer-sdk/subsystems-signals">
Optional platform modules: teams, score, data, economy, UI, audio, and signals
</Card>
<Card title="Build Your First Crafty Game" icon="rocket" href="/api-reference/crafty-sdk/build-your-first-crafty-game">
<Card title="Build Your First Summercraft Game" icon="rocket" href="/api-reference/summer-sdk/build-your-first-summer-game">
Golden-path tutorial from blank project to .pck submission
</Card>
<Card title="Multiplayer FFA Guide" icon="swords" href="/api-reference/crafty-sdk/guides/multiplayer-ffa-coin-collector">
<Card title="Multiplayer FFA Guide" icon="swords" href="/api-reference/summer-sdk/guides/multiplayer-ffa-coin-collector">
Full Coin Collector-style example with timer, collectibles, and scoring
</Card>
<Card title="Multiplayer Persistence Guide" icon="database" href="/api-reference/crafty-sdk/guides/multiplayer-persistence-rpg">
<Card title="Multiplayer Persistence Guide" icon="database" href="/api-reference/summer-sdk/guides/multiplayer-persistence-rpg">
RPG/quest example with player saves, progression, and economy
</Card>
<Card title="Team-Based Game Guide" icon="users" href="/api-reference/crafty-sdk/guides/team-based-game">
<Card title="Team-Based Game Guide" icon="users" href="/api-reference/summer-sdk/guides/team-based-game">
Teams, auto-balance, team spawns, and team scoring
</Card>
<Card title="2D Multiplayer Guide" icon="square" href="/api-reference/crafty-sdk/guides/making-a-2d-game-multiplayer">
Extend CraftyPlayer for 2D state sync and server-authoritative logic
<Card title="2D Multiplayer Guide" icon="square" href="/api-reference/summer-sdk/guides/making-a-2d-game-multiplayer">
Extend SummerPlayer for 2D state sync and server-authoritative logic
</Card>
<Card title="Turn-Based/Card Guide" icon="layout-grid" href="/api-reference/crafty-sdk/guides/making-a-turn-based-or-card-game-multiplayer">
<Card title="Turn-Based/Card Guide" icon="layout-grid" href="/api-reference/summer-sdk/guides/making-a-turn-based-or-card-game-multiplayer">
Sync turn order, hand/board state, and validate all actions on server
</Card>
<Card title="manifest.json Reference" icon="file-json" href="/api-reference/crafty-sdk/manifest-json-reference">
<Card title="manifest.json Reference" icon="file-json" href="/api-reference/summer-sdk/manifest-json-reference">
Every field, required keys, and validated examples
</Card>
<Card title="Production Launch Runbook" icon="check-check" href="/api-reference/crafty-sdk/production-launch-runbook">
<Card title="Production Launch Runbook" icon="check-check" href="/api-reference/summer-sdk/production-launch-runbook">
One linear path for fresh AI/dev sessions: integrate, test, export, submit
</Card>
<Card title="Submission Guide" icon="upload" href="/api-reference/crafty-sdk/submission-guide">
<Card title="Submission Guide" icon="upload" href="/api-reference/summer-sdk/submission-guide">
Export .pck, scanner rules, upload flow, review lifecycle, and updates
</Card>
<Card title="Testing Your Game Locally" icon="flask-conical" href="/api-reference/crafty-sdk/testing-your-game-locally">
<Card title="Testing Your Game Locally" icon="flask-conical" href="/api-reference/summer-sdk/testing-your-game-locally">
Two-process local workflow, multiplayer testing, and production-like validation loop
</Card>
<Card title="Exporting and Uploading Your Game" icon="upload-cloud" href="/api-reference/crafty-sdk/exporting-and-uploading-your-game">
<Card title="Exporting and Uploading Your Game" icon="upload-cloud" href="/api-reference/summer-sdk/exporting-and-uploading-your-game">
Game-only PCK export preset, upload pipeline, and update workflow
</Card>
<Card title="Banned APIs Reference" icon="shield-alert" href="/api-reference/crafty-sdk/banned-apis-reference">
<Card title="Banned APIs Reference" icon="shield-alert" href="/api-reference/summer-sdk/banned-apis-reference">
Complete blocked pattern list, rationale, and safe alternatives
</Card>
<Card title="AI Agent Playbook" icon="bot" href="/api-reference/crafty-sdk/ai-agent-playbook">
<Card title="AI Agent Playbook" icon="bot" href="/api-reference/summer-sdk/ai-agent-playbook">
Required file contract, banned API rules, and acceptance checklist for AI-generated games
</Card>
</CardGroup>

## Versioning

Games declare a `crafty_sdk` version in `manifest.json`. SDK changes are intended to be additive and backward-compatible.
Games declare a `summer_sdk` version in `manifest.json`. SDK changes are intended to be additive and backward-compatible.
Original file line number Diff line number Diff line change
@@ -1,14 +1,14 @@
---
title: "AI Agent Playbook"
description: "Production contract for AI-generated Crafty integrations: platform-first framing, required outputs, and acceptance checks."
description: "Production contract for AI-generated Summercraft integrations: platform-first framing, required outputs, and acceptance checks."
icon: "bot"
---

## Why This Exists

Fresh AI sessions must be able to generate code that:

- runs in Crafty runtime,
- runs in Summercraft runtime,
- passes static analysis + submission checks,
- stays server-authoritative,
- does not assume 3D template-only architecture.
Expand All @@ -17,10 +17,10 @@ This page is the strict contract for that.

## Platform-First Rule

Treat Crafty as a platform layer:
Treat Summercraft as a platform layer:

- Build game logic in Summer/Godot.
- Integrate `CraftyGame` lifecycle + player synced state.
- Integrate `SummerGame` lifecycle + player synced state.
- Use templates only when they fit the genre.

Never frame the SDK as “3D framework required.”
Expand All @@ -30,7 +30,7 @@ Never frame the SDK as “3D framework required.”
Generate these files:

- `manifest.json`
- `main.gd` (`extends CraftyGame`)
- `main.gd` (`extends SummerGame`)
- `main.tscn` (`entry_scene`)
- `player.tscn` (player root script)

Expand All @@ -40,8 +40,8 @@ If any file is missing, output is invalid.

Pick one path explicitly:

1. **3D template path**: player root script is `CraftyCharacter3D`
2. **Custom path**: player root script extends `CraftyPlayer` and defines custom synced game model
1. **3D template path**: player root script is `SummerCharacter3D`
2. **Custom path**: player root script extends `SummerPlayer` and defines custom synced game model

Do not mix assumptions from both paths.

Expand All @@ -52,7 +52,7 @@ Do not mix assumptions from both paths.
- `id` (string)
- `name` (string)
- `version` (string)
- `crafty_sdk` (string, for now `"1.0"`)
- `summer_sdk` (string, for now `"1.0"`)
- `entry_scene` (string, for example `"main.tscn"`)
- `min_players` (number)
- `max_players` (number)
Expand All @@ -67,14 +67,14 @@ If `player_scene` is present, it must point to a real scene in the project.

`main.gd` must:

- extend `CraftyGame`
- extend `SummerGame`
- implement:
- `_game_init()`
- `_game_start()`
- `_game_end()`
- `_player_joined(player)`
- `_player_left(player)`
- run authority logic server-side (`if not Crafty.is_server(): return` in `_process` when needed)
- run authority logic server-side (`if not Summer.is_server(): return` in `_process` when needed)

`main.tscn` should include:

Expand All @@ -84,15 +84,15 @@ If `player_scene` is present, it must point to a real scene in the project.
`player.tscn` should:

- use either:
- `res://sdk/crafty_character_3d.gd`, or
- your own script that extends `CraftyPlayer`
- `res://sdk/summer_character_3d.gd`, or
- your own script that extends `SummerPlayer`
- include collision + visible mesh so test runs are obvious

## Allowed vs Blocked APIs

### Allowed (use these)

- Crafty SDK systems (`Crafty`, `CraftyGame`, `CraftyPlayer`, score/teams/data/economy APIs)
- Summer SDK systems (`Summer`, `SummerGame`, `SummerPlayer`, score/teams/data/economy APIs)
- normal gameplay node logic (`Node`, `Node3D`, movement, physics, animation, signals)

### Blocked (never generate these in game scripts)
Expand All @@ -112,7 +112,7 @@ Reason: submission scanner blocks these patterns and upload fails.

For the complete and current blocked-pattern set, see:

- [Banned APIs Reference](/api-reference/crafty-sdk/banned-apis-reference)
- [Banned APIs Reference](/api-reference/summer-sdk/banned-apis-reference)

## Definition Of Done (AI Output)

Expand All @@ -121,29 +121,29 @@ An AI-generated game is "done" only if all checks pass:
1. `manifest.json` has all required fields and valid types.
2. `entry_scene` exists and loads.
3. `player_scene` exists (if present) and loads.
4. Main script extends `CraftyGame`.
5. Player path chosen explicitly (3D template or custom `CraftyPlayer` subclass).
4. Main script extends `SummerGame`.
5. Player path chosen explicitly (3D template or custom `SummerPlayer` subclass).
6. No blocked APIs appear in any `.gd` file.
7. Server-authoritative gameplay logic is on server paths.
8. Game can be exported to `.pck` and submitted.

## Safe Starter Prompt (for AI systems)

Use this prompt when generating a new Crafty game:
Use this prompt when generating a new Summercraft game:

```text
Create a minimal multiplayer Crafty game with these files only:
Create a minimal multiplayer Summer game with these files only:
manifest.json, main.gd, main.tscn, player.tscn.

Rules:
- main.gd must extend CraftyGame and implement all lifecycle hooks.
- main.gd must extend SummerGame and implement all lifecycle hooks.
- Include at least 4 spawn points in main.tscn.
- Keep authoritative gameplay state on server paths only.
- Include player_scene in manifest.json and make sure it matches player.tscn.
- Choose one player model:
- 3D template: use CraftyCharacter3D in player.tscn
- custom model: extend CraftyPlayer and sync game-specific state with set_synced/get_synced
- 3D template: use SummerCharacter3D in player.tscn
- custom model: extend SummerPlayer and sync game-specific state with set_synced/get_synced
- DO NOT use blocked APIs: OS.execute, OS.shell_open, OS.create_process, FileAccess, DirAccess, HTTPRequest, HTTPClient, JavaScriptBridge, ClassDB.instantiate, Thread.new.
- Target crafty_sdk "1.0".
- Target summer_sdk "1.0".
```

Loading
Loading