Cross-surface teleport for creative players

[jodli]

Artifacts | Task deep link | PR Walkthrough (alpha)

What problems was I solving

CreativeMod had no cross-surface teleport. The only teleport was the god-mode same-surface reposition, which explicitly notes "surface teleportation only works on player". A creative-mode player who wanted to build and test on Nauvis, another planet, or a space platform had to actually build a rocket or space platform to get there.

After this PR, a creative player can open a dedicated Teleport tab, pick any existing surface from a friendly-labeled list, and be teleported to a safe, generated position on it — instantly, with no rockets or platforms. It works in god/spectator mode, with a character (the body comes along with full inventory and equipment grid), and for the player's own surface (reposition to a fresh safe spot). The feature is gated by a new dedicated access_teleport right and degrades gracefully on vanilla 2.x without Space Age.

What user-facing changes did I ship

• A new Teleport tab in the cheats menu listing every game.surface with friendly planet/platform labels (falling back to the raw surface name on vanilla) and a single "Teleport here" apply button — scripts/gui-menu-cheats.lua
• Cross-surface teleport to a safe, chunk-generated, non-colliding position — works in god mode, with a character, or as a same-surface reposition — scripts/cheats.lua
• A new access_teleport right (admin-only / current-surface-only / free; default current-surface-only), configurable from the admin menu like every other right — scripts/rights.lua, scripts/gui-menu-admin.lua
• Localized captions, tooltips, and admin-broadcast messages in English, Simplified Chinese, and Traditional Chinese — locale/en/base.cfg, locale/zh-CN/base.cfg, locale/zh-TW/base.cfg

How I implemented it

The work was built on the mod's existing data-driven cheat / picker / rights machinery, in four phases matching the four commits.

The new right (Phase 1)

• scripts/rights.lua — added the access_teleport_level enum (admin_only=0, current_surface_only=10, free=20), default, code, and two query functions: can_player_access_teleport_menu (visible unless admin_only) and can_player_teleport_to_other_surfaces (cross-surface only when free or admin). Extended set_overall_admin_only(), set_overall_default(), and OR-ed the new menu into can_player_access_cheats_menu.
• scripts/global-util.lua — nil-guarded storage initializer so existing saves get the default without clobbering an explicit value.
• scripts/gui-menu-admin.lua — a teleport entry in access_rights_gui_data; the generic click handler picks it up automatically.
• defines.lua — admin-menu GUI name constants for the new row, plus the Teleport-tab GUI names and the teleport_target_name_button match pattern used in Phase 2.

The tab, picker, and teleport (Phase 2–3)

• scripts/gui-menu-cheats.lua — teleport_menu_gui_data, cloned from surface_cheats_menu_gui_data: same picker structure, friendly planet/platform/name captions, get_unverified_targets_function gated by the new right, and a single apply-type cheat. Registered as a teleport entry in cheats_menus_gui_data.
• scripts/cheats.lua — compute_safe_position (base-game pvp.lua pattern: spawn position → request_to_generate_chunks → force_generate_chunk_requests → find_non_colliding_position, with the tile radius converted to a small chunk radius to avoid force-generating ~16k chunks). The teleport_to_surface apply branches three ways: same surface → reposition; has character → move_player_with_character (clone the body to the destination, teleport, bind to the clone, destroy the original, restore cheat_mode, reapply character cheats); otherwise → plain cross-surface player.teleport.

Single-select picker (Phase 4)

• scripts/gui-menu-cheats.lua — a single_select_only flag on the teleport picker. In the shared click handler, control/shift are forced off when the flag is set so a plain click selects exactly one destination; the Select All button is also skipped at render time for single-select pickers. Both changes are opt-in via the flag, so all other pickers keep their multi-select behavior.

Deviations from the plan

No *plan*.md file exists for this task — the work was driven by 04-structure-outline-cross-surface-teleport.md, which the implementation followed phase by phase. All four phases are checked off in the outline. The deviations below are the decisions the outline itself recorded as "supersedes design sketch", plus one fix found during manual testing.

Implemented as planned

• All four phases: the access_teleport right end to end, the cloned Teleport tab + god-mode teleport, the character clone-move + same-surface reposition, and the single-select picker.
• Friendly planet/platform labels with vanilla fallback to surface.name.
• Right gating: admin_only hides the tab, current_surface_only shows only the own surface, free/admin shows all.

Deviations/surprises

• Apply signature (supersedes the design sketch): a surface-group cheat's apply runs as apply_to_target_function(target, value, source_player), so the destination surface is the first arg and the player is source_player — not the shape the early design sketch assumed.
• Same-surface is a reposition, not a no-op: the ticket allowed either; the implementation repositions to a fresh safe spot to keep the apply path uniform.

Additions not in plan

• Select All button skipped for single-select pickers: found in manual testing — the Select All button bypassed the single-select restriction, so it is now skipped at render time when single_select_only is set (other pickers keep it).

Items planned but not implemented

• None — all phases and acceptance criteria were completed. Out-of-scope items (teleporting other players, creating new surfaces) were intentionally not addressed.

How to verify it

Setup

git fetch origin
git checkout cross-surface-teleport-for-creative-players

Manual Testing

• In god mode, open the Teleport tab, confirm surfaces are listed with friendly labels, select one, click "Teleport here", and confirm arrival on a safe, generated (non-void/non-cliff) position.
• With a character carrying items and an equipment-grid armor, teleport cross-surface; confirm the body arrives with main inventory + equipment grid intact, no leftover/duplicate body on the origin, and cheat_mode still on.
• Select the player's own surface and confirm it repositions to a safe spot (no surface change, no error).
• On the Teleport tab, confirm ctrl/shift-click select only the clicked surface (single-select) and there is no Select All button; confirm the surface-cheats tab still supports multi-select.
• In the admin menu, confirm the Teleport access-right row with three working options; verify admin_only hides the tab for a non-admin, current_surface_only shows only the own surface, and free shows all.

Automated Tests

uv run verify.py static
uv run verify.py load

Description for the changelog

Added a Teleport tab to teleport creative-mode players to a safe position on any existing surface (god mode or character), gated by a new access_teleport right.