Admin Surface tab: blank/planet/space-platform creation + Surface Cheats relocation

[jodli]

Artifacts | Task deep link | PR Walkthrough (alpha)

What problems was I solving

CreativeMod is about removing the progression grind, yet it had no surface-creation feature anywhere. An admin who wanted a fresh space platform to prototype a design, or a planet surface that hadn't been generated yet, had to play the game normally to get there.

After this PR, an admin can create surfaces on demand from a new Surface submenu:

• a blank surface (works on vanilla and Space Age),
• a Space-Age space platform that comes up with its hub already placed,
• a Space-Age planet surface (a harmless no-op if it already exists).

Every freshly created surface immediately appears in the Surface Cheats target list for all eligible players — no menu reopen or surface change required. Space-Age paths are feature-gated in both the UI and the backend, so vanilla configurations simply don't see (or accidentally trigger) them.

What user-facing changes did I ship

• scripts/gui-menu-surface.lua - New admin-only Surface submenu with Blank surface / Space platform / Planet surface sections, mirroring the Cheats submenu's three-column navigation.
• scripts/surface-creation.lua - Backend that actually creates blank surfaces, space platforms (with hub), and planet surfaces.
• scripts/gui-menu-cheats.lua - Surface Cheats menu relocated out of the Cheats tab into the new Surface submenu, grouping it with the creation tools.
• scripts/cheats.lua - Bugfix: Teleport now exits remote view (map view) first, so it moves your actual player instead of just the remote-view camera.
• scripts/remote-interface.lua - All three creation actions exposed through the mod's remote interface.

How I implemented it

The work shipped as three vertical slices, each a full path from backend logic → remote-interface entry point → admin GUI control → live list refresh. See the PR Walkthrough above for an interactive, inline-diff tour.

Backend (scripts/surface-creation.lua)

• create_blank_surface - trims, rejects empty/duplicate names, returns a structured (success, value-or-error) result so GUI and remote share one code path.
• create_space_platform - feature-gated on space_travel; validates force + planet, creates the platform with the starter pack, then apply_starter_pack() so the hub is placed immediately.
• create_planet_surface - feature-gated; returns { surface, already_existed } so a re-create reports success, not an error.

GUI (scripts/gui-menu-surface.lua, scripts/gui-menu.lua)

• The Surface submenu - a captioned button column; clicking a section button toggles that section's content frame beside it (closing siblings first). Planet drop-downs are enumerated from game.planets in a deterministic sorted order, defaulting to nauvis, so a selected_index resolves back to a planet id with no per-player state stored.
• Submenu registration - surface entry added to submenus_gui_data, gated on raw player.admin, plus the click/selection fan-outs.

Event wiring (scripts/events.lua, scripts/gui.lua, scripts/gui-menu.lua, scripts/gui-menu-cheats.lua)

• The mod's first on_surface_created handler, forwarded down the existing events → gui → gui_menu → gui_menu_cheats chain. It routes through add_or_remove_target_in_cheats_menu_for_all_players, whose per-target access check makes the live refresh honor each player's surface-visibility rights for free.

Remote interface (scripts/remote-interface.lua)

• create_blank_surface / create_space_platform / create_planet_surface plus a resolve_force helper that falls back to game.forces["player"] when no player index is given — what lets the headless behavior tests drive force-owning creation with no connected player.

Docs (GUI-DESIGN-SYSTEM.md, README.md)

• A new GUI design-system guide documenting the menu hierarchy, styling vocabulary, event wiring, and backend/remote patterns, linked from the README.

Deviations from the plan

Compared against the structure outline (04-structure-outline-surface-creation.md).

Implemented as planned

• All three backend functions (create_blank_surface, create_space_platform, create_planet_surface) with the specified validation, return shapes, and space_travel feature-gating in both UI and backend.
• The Surface submenu with get_container_name / create_or_destroy_menu_for_player / on_gui_click / on_gui_selection_state_changed, two independent planet drop-downs, and admin-only gating.
• on_surface_created forwarded down the existing event chain into a live Surface Cheats refresh.
• Remote-interface entry points with the resolve_force headless fallback; control.lua requires inserted before gui-menu; defines.lua / locale / .luacheckrc updated.

Deviations/surprises

• The surface-cheats relocation was architecturally deeper than the outline implied. It needed a parallel surface_cheats_menus_gui_data struct, a lazy get_container_name_function wrapper (to dodge a circular require), a new public create_or_destroy_surface_cheats_menu_for_player, and a dedicated dispatch block in gui_menu_cheats.on_gui_click — not just the on_surface_created addition the plan mentioned.
• GUI layout went to the full three-column nav (button column + per-section sub-sub-menus) rather than the single inline label | textfield | create-button frame Phase 1 described. Structural upgrade, not a defect.
• Remote wrappers return only the boolean success, discarding the backend's localised error value. Consistent with the plan's "boolean for verify.py" goal, but remote callers can't inspect failure reasons.

Additions not in plan

• Teleport remote-view bugfix (scripts/cheats.lua) — unrelated to surface creation, addressed on this branch (Factorio 2.1.7 changed teleport() to no longer implicitly exit remote view).
• GUI-DESIGN-SYSTEM.md (+129 lines) — institutional knowledge captured while building the submenu.
• resolve_force extracted as a named helper; nauvis pre-selection as the default in both drop-downs.

Items planned but not implemented

• Per-player drop-down storage was skipped in favor of reading selected_index at create-time (the plan permitted either; no functional impact).

How to verify it

git fetch origin
git checkout admin-surface-and-space-platform-creation-tool

# Headless behavior + static + load checks (sandbox has Space Age enabled)
uv run verify.py static
uv run verify.py load
uv run verify.py behavior

Manual Testing

• As an admin, open the Surface submenu; confirm a non-admin cannot see it.
• Create a blank surface with a name; confirm it appears in the Surface Cheats list immediately, and that an empty or duplicate name is rejected with a message.
• (Space Age) Create a space platform orbiting a chosen planet; confirm it comes up with a hub and appears in the cheats list.
• (Space Age) Create a planet surface; confirm a second create is reported as "already existed" and no duplicate surface is made.
• On a vanilla (no Space Age) game, confirm the platform/planet sections are not shown and the blank path still works.
• In remote/map view, use Teleport and confirm your actual player moves (not just the camera).

Automated Tests

verify.py behavior adds 10 RCON asserts in the Space-Age sandbox: blank new/duplicate, platform new + hub-valid, planet new/exists/noop/no-duplicate.

Description for the changelog

Add an admin-only Surface tab to create blank surfaces (and, on Space Age, space platforms with a hub and planet surfaces) on demand, relocate Surface Cheats into it, and fix Teleport in remote view.