A12: Tutorial

A short, skippable tutorial on an island of your own: leave the barge, glide
down, walk and jump, cut materials with the boathook, place a wall, aim and
fire, and get above the line the tide will reach after its next rise.

- MatchRules.tutorial(): one player, no bots, last_team_wins off (alone is
  not a win, only the tide or a fall ends it) and starting_kit (a dock
  carbine with a full magazine and 60 cartridges, Tuning.TUTORIAL_KIT).
  Both rules go in command logs; older logs read with the defaults.
- Tutorial watches the client's own view (predicted player, world copy,
  FX) and moves on when each step is done. Instructions name the player's
  own key bindings. TutorialCard shows it under the minimap.
- TutorialPilot plays it through ClientInput for --tutorial --autoplay,
  the tests and make tutorial-check (12 seeds, all finish).
- First launch offers it (welcome screen, remembered in settings); it is
  always on the main menu; Leave in the pause menu skips it. Finishing is
  saved. --tutorial on the command line.
- make tutorial-captures; PLAY.md, the man page, ARCHITECTURE.md and
  CLAUDE.md updated.

Closes #52

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-15 05:47:31 -05:00
co-authored by Claude Opus 5.5
parent 4ea170175d
commit b604ced923
32 changed files with 1110 additions and 23 deletions
+297
View File
@@ -0,0 +1,297 @@
## A scripted player for the tutorial (A12): it plays each step the way a person at the
## keyboard would, through ClientInput (the keys it holds, the actions it presses and
## where it looks), so a headless run proves the tutorial can be finished from start
## to end with the game's real controls. `--tutorial --autoplay` uses it, and so do the
## tests and `make tutorial-check`.
##
## It knows only what the client knows: its own predicted player and the client's copy
## of the world.
class_name TutorialPilot
extends RefCounted
const TICKS: int = Tuning.TICK_RATE_HZ
## Looks for something to cut or shoot this far away.
const SEARCH_METRES: float = 60.0
## Gives up on a target it makes no headway towards for this long.
const STUCK_SECONDS: float = 6.0
## Fires from no farther than this.
const FIRE_METRES: float = 20.0
## Climbs to ground at least this far above the tide line.
const CLIMB_MARGIN_METRES: float = 3.0
var tutorial: Tutorial
var input: ClientInput
var _target: int = -1
var _skipped: Dictionary = {}
var _goal: Vector3 = Vector3.INF
var _bad_goals: Array[Vector3] = []
var _progress_at: Vector3 = Vector3.INF
var _progress_tick: int = 0
var _best_distance: float = INF
var _build_turns: int = 0
var _build_tick: int = -1
var _map_tick: int = -1
var _walk_yaw: float = 0.0
func _init(for_tutorial: Tutorial, with_input: ClientInput) -> void:
tutorial = for_tutorial
input = with_input
## The command for `tick`, made by setting the input as a player's hands would.
func command(tick: int, game: ClientGame) -> PlayerCommand:
input.move = Vector2.ZERO
input.buttons = 0
if game.world == null or not game.playing():
return input.command(tick)
var me: SimEntity = game.prediction.player
var world: Simulation = game.world
if tutorial.step != Tutorial.BUILD and input.build_mode:
input.act("build")
match tutorial.step:
Tutorial.LEAP:
_face_centre(me)
if tick > 3 * TICKS and world.ground.terrain_height(me.position.x, me.position.z) > Tuning.ISLAND_BEACH_TOP + 4.0:
input.buttons = PlayerCommand.BUTTON_JUMP
Tutorial.GLIDE:
_face_centre(me)
input.move = Vector2(0.0, 1.0)
Tutorial.MOVE:
input.yaw = _walk_yaw
input.pitch = 0.0
input.move = Vector2(0.0, 1.0)
if tick % (2 * TICKS) == 0:
input.buttons = PlayerCommand.BUTTON_JUMP
if _stuck(tick, me):
_walk_yaw += PI * 0.5
Tutorial.HARVEST:
_harvest(tick, me, world)
Tutorial.BUILD:
_build(tick, me)
Tutorial.FIRE:
_fire(tick, me, world)
Tutorial.TIDE:
_climb(tick, me, world)
return input.command(tick)
func _face_centre(me: SimEntity) -> void:
var centre: float = Tuning.WORLD_SIZE_METRES * 0.5
input.yaw = atan2(centre - me.position.x, centre - me.position.z)
input.pitch = deg_to_rad(-12.0)
## Selects slot `number` (0 the boathook) as the number key would.
func _hold_slot(number: int) -> void:
if input.slot != number:
input.act("slot_%d" % number)
## Walks up to the nearest standing prop and swings the boathook at it.
func _harvest(tick: int, me: SimEntity, world: Simulation) -> void:
_hold_slot(0)
if _target < 0 or not world.props.is_standing(_target):
_target = _nearest_prop(me, world)
_reset_progress(tick, me)
if _target < 0:
_wander(tick, me)
return
var box: AABB = world.props.boxes[_target]
var eye: Vector3 = Harvest.eye(me)
var centre: Vector3 = box.get_center()
var aim: Vector3 = Vector3(centre.x, clampf(eye.y, box.position.y + 0.2, box.end.y - 0.1), centre.z)
_look_at(eye, aim)
if PropSet._distance_to_box(box, eye) <= Harvest.reach() - 0.6:
input.buttons = PlayerCommand.BUTTON_FIRE
_reset_progress(tick, me)
return
input.pitch = 0.0
input.move = Vector2(0.0, 1.0)
if tick % (2 * TICKS) == TICKS:
input.buttons = PlayerCommand.BUTTON_JUMP
if _stuck(tick, me, PropSet._distance_to_box(box, me.position)):
_skipped[_target] = true
_target = -1
## Build mode, the wall, the material it has most of, and a press of fire; a quarter
## turn after each try that places nothing.
func _build(tick: int, me: SimEntity) -> void:
if not input.build_mode:
input.act("build")
if input.build_kind != StructureSet.WALL:
input.act("slot_%d" % StructureSet.WALL)
var best: int = 0
for index: int in me.materials.size():
if me.materials[index] > me.materials[best]:
best = index
if input.material != best:
input.act("material")
return
input.pitch = 0.0
if _build_tick < 0:
_build_tick = tick
input.yaw = float(me.yaw) / PlayerCommand.YAW_STEPS * TAU
var since: int = tick - _build_tick
if since % TICKS == 0 and since > 0:
_build_turns += 1
input.yaw += PI * 0.5
if _build_turns % 4 == 0:
# No room here: step aside and try again.
input.move = Vector2(1.0, 0.0)
# Half a second to look at the ghost, then a press of fire, each try.
var phase: int = since % TICKS
if phase >= TICKS / 2 and phase < TICKS / 2 + 3:
input.buttons = PlayerCommand.BUTTON_FIRE
elif phase > TICKS / 2 + 3 and _build_turns % 4 == 0 and _build_turns > 0:
input.move = Vector2(1.0, 0.0)
## The carbine, aimed down the sights at the nearest prop in range, fired in taps.
func _fire(tick: int, me: SimEntity, world: Simulation) -> void:
_hold_slot(1)
if _target < 0 or not world.props.is_standing(_target):
_target = _nearest_prop(me, world)
_reset_progress(tick, me)
if _target < 0:
_wander(tick, me)
return
var box: AABB = world.props.boxes[_target]
var eye: Vector3 = Harvest.eye(me)
var centre: Vector3 = box.get_center()
_look_at(eye, Vector3(centre.x, clampf(eye.y, box.position.y + 0.3, box.end.y - 0.2), centre.z))
if eye.distance_to(centre) <= FIRE_METRES:
input.buttons = PlayerCommand.BUTTON_AIM
if tick % 10 < 2:
input.buttons |= PlayerCommand.BUTTON_FIRE
if tick % (3 * TICKS) == 0 and tick > 0:
# A miss or a blocked line: try the next one.
_skipped[_target] = true
_target = -1
return
input.pitch = 0.0
input.move = Vector2(0.0, 1.0)
if _stuck(tick, me, eye.distance_to(centre)):
_skipped[_target] = true
_target = -1
## Opens the chart for a moment, closes it, then walks to the nearest ground well above
## the tide line it must beat.
func _climb(tick: int, me: SimEntity, world: Simulation) -> void:
if _map_tick < 0:
_map_tick = tick
if not input.map_open:
input.act("map")
return
if input.map_open:
if tick - _map_tick >= TICKS:
input.act("map")
return
var line: float = Tutorial.tide_line(world.tide, world.tick) + Tutorial.TIDE_MARGIN_METRES
if me.position.y >= line + 0.5 and me.on_ground:
return
if _goal == Vector3.INF:
_goal = _high_ground(me, world, line + CLIMB_MARGIN_METRES)
_reset_progress(tick, me)
if _goal == Vector3.INF:
_wander(tick, me)
return
input.yaw = atan2(_goal.x - me.position.x, _goal.z - me.position.z)
input.pitch = 0.0
input.move = Vector2(0.0, 1.0)
if tick % TICKS == 0:
input.buttons = PlayerCommand.BUTTON_JUMP | PlayerCommand.BUTTON_SPRINT
else:
input.buttons = PlayerCommand.BUTTON_SPRINT
var flat: float = Vector2(_goal.x - me.position.x, _goal.z - me.position.z).length()
if _stuck(tick, me, flat):
_bad_goals.append(_goal)
_goal = Vector3.INF
## The nearest point of the terrain at least `height` up, from rings around the player,
## leaving out goals already given up on.
func _high_ground(me: SimEntity, world: Simulation, height: float) -> Vector3:
for ring: int in range(1, 40):
var radius: float = float(ring) * 6.0
var points: int = 8 + ring * 2
for index: int in points:
var angle: float = TAU * float(index) / float(points)
var x: float = me.position.x + sin(angle) * radius
var z: float = me.position.z + cos(angle) * radius
if x < 0.0 or z < 0.0 or x > Tuning.WORLD_SIZE_METRES or z > Tuning.WORLD_SIZE_METRES:
continue
var y: float = world.ground.terrain_height(x, z)
if y < height:
continue
var spot: Vector3 = Vector3(x, y, z)
var refused: bool = false
for bad: Vector3 in _bad_goals:
if Vector2(bad.x - x, bad.z - z).length() < 15.0:
refused = true
if not refused:
return spot
return Vector3.INF
func _nearest_prop(me: SimEntity, world: Simulation) -> int:
var best: int = -1
var best_distance: float = INF
for prop: int in world.props.near(me.position, SEARCH_METRES):
if _skipped.has(prop) or not world.props.is_standing(prop):
continue
var box: AABB = world.props.boxes[prop]
if box.position.y < world.sea_level + 0.5 or absf(box.position.y - me.position.y) > 6.0:
continue
var distance: float = PropSet._distance_to_box(box, me.position)
if distance < best_distance:
best_distance = distance
best = prop
return best
func _look_at(eye: Vector3, point: Vector3) -> void:
var to: Vector3 = point - eye
input.yaw = atan2(to.x, to.z)
input.pitch = atan2(to.y, Vector2(to.x, to.z).length())
## Walks on in some direction when there's nothing near to go to.
func _wander(tick: int, me: SimEntity) -> void:
input.yaw = _walk_yaw
input.pitch = 0.0
input.move = Vector2(0.0, 1.0)
if tick % (2 * TICKS) == 0:
input.buttons = PlayerCommand.BUTTON_JUMP
if _stuck(tick, me):
_walk_yaw += PI * 0.5
func _reset_progress(tick: int, me: SimEntity) -> void:
_progress_at = me.position
_progress_tick = tick
_best_distance = INF
## True, once, after STUCK_SECONDS without headway: closer to the target by a metre
## when `distance` is given, else a few metres from where it was.
func _stuck(tick: int, me: SimEntity, distance: float = -1.0) -> bool:
if _progress_at == Vector3.INF:
_reset_progress(tick, me)
var moved: bool
if distance >= 0.0:
moved = distance < _best_distance - 1.0
if moved:
_best_distance = distance
else:
moved = me.position.distance_to(_progress_at) > 3.0
if moved:
_progress_at = me.position
_progress_tick = tick
elif tick - _progress_tick > roundi(STUCK_SECONDS * TICKS):
_reset_progress(tick, me)
return true
return false