Your First Defold Steam Desktop Collection and Save Audit in One Evening - 2026 Beginner Pipeline

You bundled Defold for Windows. The editor run was clean. Steam players install the demo, reach the first checkpoint, quit, relaunch—and progress is gone. You used sys.save in the tutorial sense, but the packaged app wrote to a different root than you assumed, or your bootstrap collection was not the one Steam loads first.

May–October 2026 is when HTML5-first and 2D teams—many on Defold beside GDevelop and GameMaker—add Steam desktop demos for Next Fest. This Tutorials & Beginner-First pipeline is not a full Steamworks depot guide (see playtest branch evening); it is the Defold-specific collection and save audit you run once per build_id before upload.

Pair with BUILD_RECEIPT, Wednesday demo smoke, and HTML5-first storefront analysis.

Who this is for and what you get

Time: one evening (3–4 hours first bundle; 50–70 minutes on repeat).
Prerequisites: Defold project that runs in editor, Desktop platform added, Steamworks app with depot planned.

Why this matters now (May 2026)

1. HTML5 → Steam path — Defold ships web and mobile first; desktop bundle layout surprises teams at fest week.
2. Collection bootstrap bugs — Wrong game.project main collection or proxy load order shows only in packaged builds.
3. sys.save root drift — Save file location differs between editor, dev app, and Steam install.
4. Fest smoke culture — Wednesday demo smoke needs a binary that boots and saves.
5. Cross-engine expectations — Players compare your demo to Construct and GameMaker discipline; evidence culture transfers.

Direct answer: Map collections → audit save roots → bundle desktop → run gates D1–D5 → write receipt → upload.

What you will have after one evening

• collection_map_v1.json listing every collection and bootstrap role
• save_root_map_v1.json with slot keys and OS paths verified on standalone
• export/DefoldSteam/ bundle folder ready for SteamPipe
• defold_steam_audit_receipt_v1.json
• Main-menu screenshot from packaged app, not editor
• Visible build_label in-game matching receipt

Evening timeline

Mental model — editor vs packaged desktop

Tonight ends at packaged desktop on a PC without Defold editor (gate D3). Installed Steam smoke is the next session.

Step 1 — Collection map (Gate D1)

Defold games are collections of game objects, not monolithic scenes. Fest bugs often start with wrong collection loaded first.

Create collection_map_v1.json:

{
  "schema": "collection_map_v1",
  "project_version": "0.3.0-fest-audit",
  "main_collection": "/main/main.collection",
  "bootstrap": [
    { "collection": "/main/main.collection", "role": "retail_entry", "proxy_loads": ["/levels/level1.collectionc"] }
  ],
  "excluded_from_retail": ["/debug/debug_overlay.collection"],
  "factories": [
    { "id": "enemy_factory", "collection": "/entities/enemy.go" }
  ]
}

D1 pass checklist:

• [ ] game.project main collection matches main_collection in JSON
• [ ] No debug collection in retail bootstrap path
• [ ] Every collectionproxy target listed with purpose
• [ ] Loading screen collection documented if used

collectionproxy discipline

Outbound: Defold collection manual (verify against your editor version).

Lua module pattern for saves (beginner-friendly)

Wrap raw sys.save behind one module save_service.lua:

local M = {}
local KEY = "/demo_save_v1"
local VERSION = 1

function M.save_state(state)
  state._version = VERSION
  local ok = sys.save(KEY, state)
  return ok
end

function M.load_state()
  local state = sys.load(KEY)
  if not state or state._version ~= VERSION then
    return nil
  end
  return state
end

return M

Why: One place to bump VERSION, log failures, and ban debug fields from persisted tables. Gate D2 reviews only this module’s contract.

Step 2 — Save root audit (Gate D2)

Defold persistence usually flows through sys.save / sys.load or wrapped modules.

Document save_root_map_v1.json:

{
  "schema": "save_root_map_v1",
  "slots": [
    {
      "slot_id": "demo_progress",
      "api": "sys.save",
      "key": "/demo_save_v1",
      "verified_path_note": "See packaged app log — typically under app support directory",
      "forbidden": ["hardcoded absolute paths", "editor-only test keys"]
    }
  ],
  "save_format_version": 1,
  "faq_alignment": "local progress only; no Steam Cloud in demo"
}

D2 test script (packaged app only):

1. Delete known save file if exists (document path after first run).
2. Launch packaged app; reach checkpoint.
3. Confirm sys.save returns without error (log in script).
4. Quit fully.
5. Relaunch; confirm load restores checkpoint.
6. Log actual path from print(sys.get_save_file(key, path)) in development build only—remove noisy prints before retail.

Align FAQ save claims with map.

Save table hygiene

Cross-read GDevelop save-path challenge for parallel HTML5-first discipline.

Factories, atlases, and included resources (D1 extension)

Fest demos still fail when assets are missing from bundled collections:

Run Project → Build report (or bundle log) and attach warnings to gate1_pass.log. Pink/missing textures in packaged app are D3 fails, not art polish issues.

Input bindings before bundle

Deck testing is optional until store claims Deck—honesty beats checkbox features.

Step 3 — game.project and desktop bundle (Gate D3)

Open game.project and record in game_project_audit.md:

Bundle steps (conceptual):

1. Project → Bundle → Desktop → Windows x86_64 (or your target).
2. Output to clean folder export/DefoldSteam/.
3. Confirm .exe or launcher present per Defold version output layout.
4. Double-click run without editor open.

D3 pass:

• [ ] App launches within 90s cold boot
• [ ] build_label visible on title (add GUI text bound to sys.get_config_info)
• [ ] No missing .collectionc errors in log
• [ ] Working directory writable for saves

Zip contents for SteamPipe per depot discipline—not an extra parent folder named export.

Step 4 — Golden path boot (Gate D4)

Write five steps in demo-golden-path.md:

1. Launch to title
2. Start demo run
3. Reach first checkpoint (flag variable)
4. Trigger save (autosave or interact)
5. Observe HUD readable at 1080p

Run 60 seconds of gameplay after first input—same vocabulary as Wednesday smoke.

D4 pass: No soft-lock; first collection proxy completes.

Step 5 — Save round-trip and quit (Gate D5)

After D4, execute save round-trip twice:

D5 fail blocks upload—even if D4 felt fine.

Debug and console discipline

Disable debug keys for retail demo per developer console opinion. Defold debug scripts should not ship in fest bundle profile.

defold_steam_audit_receipt_v1.json

{
  "schema": "defold_steam_audit_receipt_v1",
  "build_label": "df-nextfest-2026-05-24-rc1",
  "defold_version": "1.10.0",
  "platform": "x86_64-win32",
  "audited_at_utc": "2026-05-24T18:00:00Z",
  "gates": {
    "D1_collection_map": "pass",
    "D2_save_root": "pass",
    "D3_bundle_layout": "pass",
    "D4_golden_boot": "pass",
    "D5_save_roundtrip": "pass"
  },
  "main_collection": "/main/main.collection",
  "save_format_version": 1,
  "paired_build_receipt": "release-evidence/05-operations/receipts/df-nextfest-2026-05-24-rc1.json",
  "notes": "Win11; no Steamworks extension yet"
}

Archive under release-evidence/defold/. Copy build_label into BUILD_RECEIPT.

After audit — Steam upload handoff

1. Upload bundle to depot root.
2. Capture Steam build id in BUILD_RECEIPT.
3. Run Wednesday demo smoke on installed build.
4. Run metadata diff before promotion.

Packaged audit does not replace installed smoke.

Cross-engine freeze family

Use one evidence taxonomy—do not fork folders per engine brand.

HTML5 itch + Steam dual SKU

If you ship itch HTML5 and Steam desktop:

See dual-SKU economics. Re-run all gates when switching platform target.

Native extensions and Steamworks

If you add Steamworks extension later:

Optional D6 row in receipt when extension enabled.

Save migration mini-ladder (when demo scope changes)

If you add a floor mid-fest:

Never silently read v1 blobs with v2 schema—players call it corruption. Pattern aligns with Construct save migration.

Performance smoke on packaged build (optional D4b)

Fest demos need stable more than max—log “D4b optional pass” in receipt notes.

Playtest branch before public fest

Upload audited bundle to friends-and-family playtest branch before fest branch. Receipt proves folder sanity; playtest proves install path.

Distributed handoff

When Asia-EU handoff bundles overnight:

• EU morning verifies collection_map hash unchanged
• Asia logs Defold editor version in BUILD_RECEIPT
• Never promote without D5 on installed build

Incident response when saves fail live

Operating review hook

Four-Friday operating reviews Block 3:

• Audits filed per promoted build_id
• D2 vs D5 failure ratio
• Qualitative refund tags “lost save”

Month-one adoption ladder

Worked example (composite solo dev)

Lesson: Editor never loaded wrong proxy order; bundle did.

Common mistakes (seven)

1. Auditing saves in editor only — D2 requires packaged app.
2. Wrong main collection in game.project — D1 fail.
3. Non-serializable save tables — D5 intermittent fail.
4. Debug collection left in bootstrap — Players see dev UI.
5. No build_label — Support cannot correlate refunds.
6. Skipping installed smoke — Depot path differs from local bundle folder.
7. Assuming web save equals desktop — Dual SKU needs two map rows.

Pro tips (six)

1. Log save path once in dev bundle, strip prints for retail.
2. Screenshot title screen with build_label every audit.
3. Commit collection_map beside source—diff on fest week.
4. Second machine test monthly.
5. Pair with 18 playtest tools after smoke passes.
6. Block fest marketing cap spend on D5 fail.

collectionproxy load order (advanced D1 table)

When your demo streams levels:

Document unload: if proxy does not unload previous world, memory climbs and saves may reference destroyed instances—fail D4 if RAM doubles after three loads.

Beginner quick start (30 seconds)

Defold fest shipping is collections + saves + bundle, not “press export.” Tonight: list collections, test save on the built exe, file receipt. Steam upload waits until gates pass.

Treat this like learning Git for the first time: awkward for one evening, then automatic every promotion.

Second-week habits

• Re-run D2 only when save schema changes.
• Full D1–D5 on any main_collection change.
• Attach receipt path to Slack promotion template.

CI hook (optional)

test -f release-evidence/defold/defold_steam_audit_receipt_v1.json || exit 2
jq -e '.gates.D5_save_roundtrip == "pass"' release-evidence/defold/defold_steam_audit_receipt_v1.json || exit 3

Match validate-packet exit code style.

Partner packet crosswalk

Attach to partner ZIP 01_builds/:

• collection_map_v1.json
• save_root_map_v1.json
• defold_steam_audit_receipt_v1.json

Q3 diligence asks how saves work—maps answer without fake retention stats.

Non-repetition note (editorial)

First URL dedicated to Defold Steam collection + save audit; Lua scripting overview mentions Defold but does not cover fest export gates. Consumed Blog-Planner High #1 after May 23 refill—not escape hatch.

Key takeaways

• Collections and save roots are the Defold fest risk surface—not only “does it export.”
• Gates D1–D5: map, save audit, bundle, golden boot, round-trip.
• defold_steam_audit_receipt_v1.json pairs with BUILD_RECEIPT and Wednesday smoke.
• Packaged desktop test is mandatory; editor play is not proof.
• game.project main collection must match collection_map_v1.json.
• Dual itch/Steam SKUs need separate save map rows.
• Debug collections must stay out of retail bootstrap.
• Installed Steam smoke still required after this audit.
• Cross-engine teams share one evidence folder taxonomy.
• Non-serializable tables are the silent D5 killer.

Evidence folder layout

release-evidence/
  defold/
    collection_map_v1.json
    save_root_map_v1.json
    defold_steam_audit_receipt_v1.json
    screenshots/
      title_build_label.png
    logs/
      gate1_pass.log
      gate3_bundle.log

Friday Block 5 spot-checks this folder monthly.

Promotion gate checklist (copy-paste)

[ ] defold_steam_audit_receipt_v1.json all gates pass
[ ] build_label matches BUILD_RECEIPT and in-game HUD
[ ] collection_map matches game.project main collection
[ ] Wednesday metadata diff GREEN
[ ] Wednesday demo smoke S4–S6 GREEN on installed build
[ ] FAQ save wording matches save_root_map

Refund dashboard crosswalk

When refund signals spike “progress lost,” verify:

FAQ

We use DefoldKit or custom CI bundle—skip?
No—map collections and save paths regardless of bundle button.

Does this replace GDevelop seven-day challenge?
Parallel engine; run the audit matching your stack.

Steamworks extension day one?
Optional D6; start without SDK for first demo.

macOS depot too?
Re-run all gates; save paths differ.

How long per repeat audit?
Under 70 minutes when maps exist.

Does Defold use the same paths as GameMaker?
No—follow this map; cross-read GameMaker export sanity only for evidence culture, not file paths.

Steam Deck note (optional)

If your store page mentions Deck support, run D4–D5 once on Deck hardware after Windows pass—log in receipt notes. Defold projects still need a readable pause menu at 1280×800 even when a future Unity glyph article covers Input System tables for other stacks.

Snippet-friendly answers

How do I export Defold to Steam?
Map collections, audit sys.save on a packaged desktop bundle, file defold_steam_audit_receipt_v1.json, upload via SteamPipe, then run installed smoke before branch promotion.

Why does Defold save work in editor but not Steam?
Usually wrong save key, non-serializable state, or testing editor instead of bundled app.

What is a collection map?
A JSON list of which Defold collections boot, load via proxy, and stay out of retail builds.

Conclusion

Defold rewards fast iteration—and punishes unmapped collections on desktop.

Spend one evening on D1–D5. File the receipt. Upload only after saves survive a packaged quit.

If your team already runs evidence cycles, slot this audit in the light week before a heavy content push—collection truth is part of shipping, not a detour.

Bookmark the five gate names on a sticky note beside your monitor: D1 map, D2 save, D3 bundle, D4 boot, D5 round-trip. When a producer asks “can we promote tonight,” the answer is a file path in release-evidence/defold/, not a feeling about yesterday’s editor session.

Next reads: BUILD_RECEIPT pipeline, Wednesday demo smoke, GameMaker export sanity.