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:
@@ -0,0 +1,201 @@
|
||||
extends TestCase
|
||||
|
||||
## A12: the tutorial. A match alone that only the tide ends, with a weapon to learn on;
|
||||
## steps that judge what the player did from the client's own view; instructions that
|
||||
## name the player's own keys; a scripted player that finishes it; and the menus that
|
||||
## offer it on the first launch and keep it on the main menu.
|
||||
|
||||
const PATH: String = "user://test_tutorial_settings.cfg"
|
||||
const DT: float = 1.0 / Tuning.TICK_RATE_HZ
|
||||
|
||||
|
||||
func after_each() -> void:
|
||||
super.after_each()
|
||||
DirAccess.remove_absolute(ProjectSettings.globalize_path(PATH))
|
||||
|
||||
|
||||
func test_a_tutorial_match_alone_plays_on_and_starts_with_the_kit() -> void:
|
||||
var loop: ServerLoop = ServerLoop.new(5, 1, 0, MatchRules.tutorial())
|
||||
var flow: Match = loop.match_flow
|
||||
for _tick: int in 3:
|
||||
loop.run_tick()
|
||||
assert_true(flow.in_match(), "one player alone isn't the last one standing in the tutorial")
|
||||
var me: SimEntity = flow.sim.entities.find(int(flow.entity_of[flow.participants[0]]))
|
||||
var weapon: int = ItemCatalog.code_of(String(Tuning.TUTORIAL_KIT["weapon"]))
|
||||
assert_eq(Inventory.count_of(me, weapon), 1, "carries the kit's weapon")
|
||||
assert_true(me.slot_rounds[0] > 0, "loaded")
|
||||
assert_eq(Inventory.count_of(me, ItemCatalog.code_of(String(Tuning.TUTORIAL_KIT["ammo"]))), int(Tuning.TUTORIAL_KIT["spare"]))
|
||||
for _tick: int in 20 * Tuning.TICK_RATE_HZ:
|
||||
loop.run_tick()
|
||||
assert_true(flow.in_match(), "still playing twenty seconds on")
|
||||
|
||||
|
||||
func test_ordinary_rules_still_end_a_match_with_one_team_left() -> void:
|
||||
var rules: MatchRules = MatchRules.immediate()
|
||||
rules.max_players = 1
|
||||
rules.min_players = 1
|
||||
rules.fill_with_bots = false
|
||||
var loop: ServerLoop = ServerLoop.new(5, 1, 0, rules)
|
||||
for _tick: int in 3:
|
||||
loop.run_tick()
|
||||
assert_eq(loop.match_flow.phase, Match.RESULTS, "alone under the usual rules is a win at once")
|
||||
assert_eq(loop.match_flow.winners.size(), 1)
|
||||
|
||||
|
||||
func test_the_tutorial_ends_when_its_player_falls() -> void:
|
||||
var loop: ServerLoop = ServerLoop.new(5, 1, 0, MatchRules.tutorial())
|
||||
var flow: Match = loop.match_flow
|
||||
for _tick: int in 3:
|
||||
loop.run_tick()
|
||||
assert_true(flow.in_match())
|
||||
flow.leave(int(flow.participants[0]))
|
||||
loop.run_tick()
|
||||
assert_false(flow.in_match(), "nobody left standing ends it")
|
||||
|
||||
|
||||
func test_instructions_name_the_players_own_keys() -> void:
|
||||
var tutorial: Tutorial = Tutorial.new()
|
||||
assert_true(tutorial.instruction().contains("[Space]"), tutorial.instruction())
|
||||
var keys: KeyBindings = KeyBindings.new()
|
||||
assert_eq(keys.bind("jump", KEY_J), "")
|
||||
tutorial.bindings = keys
|
||||
assert_true(tutorial.instruction().contains("[J]"), "rebound jump shows: " + tutorial.instruction())
|
||||
for step: int in Tutorial.STEP_NAMES.size():
|
||||
tutorial.step = step
|
||||
assert_false(tutorial.instruction().is_empty(), "step %s says what to do" % Tutorial.STEP_NAMES[step])
|
||||
assert_false(tutorial.instruction().contains("%"), "no unfilled format in %s" % Tutorial.STEP_NAMES[step])
|
||||
assert_eq(tutorial.counter(), "Tutorial complete")
|
||||
|
||||
|
||||
func test_the_scripted_player_finishes_the_tutorial_through_the_client() -> void:
|
||||
var result: Dictionary = preload("res://tools/tutorial_check.gd").play(3, 300.0)
|
||||
assert_true(bool(result["finished"]), "finished: %s" % result)
|
||||
for step: String in ["leap", "glide", "move", "harvest", "build", "fire", "tide"]:
|
||||
assert_true(float(result["steps"][step]) > 0.0, "%s took some time: %s" % [step, result])
|
||||
|
||||
|
||||
func test_steps_wait_for_the_player_to_act() -> void:
|
||||
var session: ClientSession = ClientSession.new()
|
||||
session.play_tutorial(3)
|
||||
# Nobody at the keys: the barge flies on, and the tutorial waits on its first step
|
||||
# until the barge throws everyone off at the end of its route.
|
||||
for _frame: int in 3 * Tuning.TICK_RATE_HZ:
|
||||
session.pump(DT)
|
||||
assert_true(session.game.playing())
|
||||
assert_eq(session.tutorial.step, Tutorial.LEAP)
|
||||
assert_eq(session.game.prediction.player.drop_state, Drop.ABOARD)
|
||||
session.free()
|
||||
|
||||
|
||||
func test_settings_remember_the_offer_and_the_finish() -> void:
|
||||
var settings: GameSettings = GameSettings.new()
|
||||
assert_false(settings.tutorial_offered)
|
||||
assert_false(settings.tutorial_done)
|
||||
settings.tutorial_offered = true
|
||||
settings.tutorial_done = true
|
||||
assert_eq(settings.save(PATH), OK)
|
||||
var loaded: GameSettings = GameSettings.load_from(PATH)
|
||||
assert_true(loaded.tutorial_offered)
|
||||
assert_true(loaded.tutorial_done)
|
||||
|
||||
|
||||
func test_the_first_launch_offers_it_and_not_now_is_remembered() -> void:
|
||||
var tree: SceneTree = Engine.get_main_loop() as SceneTree
|
||||
var shell: AppShell = AppShell.new(GameSettings.new(), PATH)
|
||||
shell.grab_mouse = false
|
||||
tree.root.add_child(shell)
|
||||
assert_eq(shell.menus.current, "welcome")
|
||||
(shell.menus.buttons_of("welcome")["Not now"] as Button).pressed.emit()
|
||||
assert_eq(shell.menus.current, "main")
|
||||
assert_null(shell.session)
|
||||
assert_true(GameSettings.load_from(PATH).tutorial_offered, "saved")
|
||||
shell.free()
|
||||
var again: AppShell = AppShell.new(GameSettings.load_from(PATH), PATH)
|
||||
again.grab_mouse = false
|
||||
tree.root.add_child(again)
|
||||
assert_eq(again.menus.current, "main", "not offered twice")
|
||||
again.free()
|
||||
|
||||
|
||||
func test_the_tutorial_starts_from_the_welcome_and_the_main_menu() -> void:
|
||||
var tree: SceneTree = Engine.get_main_loop() as SceneTree
|
||||
for pair: Array in [["welcome", "Start the tutorial"], ["main", "Tutorial"]]:
|
||||
var settings: GameSettings = GameSettings.new()
|
||||
settings.tutorial_offered = pair[0] == "main"
|
||||
var shell: AppShell = AppShell.new(settings, PATH)
|
||||
shell.grab_mouse = false
|
||||
tree.root.add_child(shell)
|
||||
assert_eq(shell.menus.current, pair[0])
|
||||
var buttons: Dictionary = shell.menus.buttons_of(pair[0])
|
||||
assert_true(buttons.has(pair[1]), "%s has '%s'" % pair)
|
||||
(buttons[pair[1]] as Button).pressed.emit()
|
||||
assert_not_null(shell.session, "a tutorial began from %s" % pair[0])
|
||||
assert_not_null(shell.session.tutorial)
|
||||
assert_not_null(shell.session.local, "offline")
|
||||
assert_true(settings.tutorial_offered)
|
||||
assert_false(shell.menus.visible)
|
||||
shell.leave()
|
||||
assert_eq(shell.menus.current, "main", "Leave skips it, back to the main menu")
|
||||
shell.free()
|
||||
|
||||
|
||||
func test_finishing_is_saved() -> void:
|
||||
var tree: SceneTree = Engine.get_main_loop() as SceneTree
|
||||
var settings: GameSettings = GameSettings.new()
|
||||
settings.tutorial_offered = true
|
||||
var shell: AppShell = AppShell.new(settings, PATH)
|
||||
shell.grab_mouse = false
|
||||
tree.root.add_child(shell)
|
||||
shell.start_tutorial()
|
||||
shell.session.tutorial.step = Tutorial.DONE
|
||||
shell.watch_tutorial()
|
||||
assert_true(GameSettings.load_from(PATH).tutorial_done)
|
||||
shell.free()
|
||||
|
||||
|
||||
func test_the_card_shows_the_step_once_playing() -> void:
|
||||
var card: TutorialCard = TutorialCard.new()
|
||||
(Engine.get_main_loop() as SceneTree).root.add_child(card)
|
||||
var tutorial: Tutorial = Tutorial.new()
|
||||
card.show_tutorial(tutorial, false)
|
||||
assert_false(card.visible, "hidden before the match")
|
||||
tutorial.step = Tutorial.BUILD
|
||||
card.show_tutorial(tutorial, true)
|
||||
assert_true(card.visible)
|
||||
assert_true(card.size.y > 60.0, "sized to its words")
|
||||
card.free()
|
||||
|
||||
|
||||
func test_the_command_line_asks_for_it() -> void:
|
||||
var config: ClientConfig = ClientConfig.parse(PackedStringArray(["--tutorial", "--autoplay", "--seed=4"]))
|
||||
assert_true(config.is_valid(), str(config.errors))
|
||||
assert_true(config.tutorial and config.asked and config.autoplay)
|
||||
assert_false(ClientConfig.parse(PackedStringArray(["--tutorial", "--connect=192.0.2.7"])).is_valid())
|
||||
assert_false(ClientConfig.parse(PackedStringArray(["--tutorial", "--duos"])).is_valid())
|
||||
assert_eq(ClientConfig.game_args(PackedStringArray(), PackedStringArray(["--tutorial"])), PackedStringArray(["--tutorial"]))
|
||||
|
||||
|
||||
func test_command_logs_keep_the_new_rules_and_read_old_ones() -> void:
|
||||
var log: CommandLog = CommandLog.new(7, 1, MatchRules.tutorial())
|
||||
var header: Dictionary = log.header()
|
||||
assert_eq(header["rules"]["last_team_wins"], false)
|
||||
assert_eq(header["rules"]["starting_kit"], true)
|
||||
var back: CommandLog = CommandLog.from_bytes(log.to_bytes())
|
||||
assert_not_null(back)
|
||||
assert_false(back.rules.last_team_wins)
|
||||
assert_true(back.rules.starting_kit)
|
||||
# A log written before A12 has neither rule, and reads with the defaults.
|
||||
var old: Dictionary = header.duplicate(true)
|
||||
old["rules"].erase("last_team_wins")
|
||||
old["rules"].erase("starting_kit")
|
||||
var head: PackedByteArray = JSON.stringify(old).to_utf8_buffer()
|
||||
var out: StreamPeerBuffer = StreamPeerBuffer.new()
|
||||
out.big_endian = false
|
||||
out.put_data(CommandLog.MAGIC.to_ascii_buffer())
|
||||
out.put_u32(head.size())
|
||||
out.put_data(head)
|
||||
out.put_u32(0)
|
||||
var earlier: CommandLog = CommandLog.from_bytes(out.data_array)
|
||||
assert_not_null(earlier, "an older log still reads")
|
||||
assert_true(earlier.rules.last_team_wins)
|
||||
assert_false(earlier.rules.starting_kit)
|
||||
@@ -0,0 +1 @@
|
||||
uid://s4xeekurih46
|
||||
@@ -0,0 +1,9 @@
|
||||
[gd_scene load_steps=2 format=3]
|
||||
|
||||
[ext_resource type="Script" path="res://test/capture/menu_scene.gd" id="1"]
|
||||
|
||||
[node name="CaptureMenu" type="Control"]
|
||||
script = ExtResource("1")
|
||||
screen = "welcome"
|
||||
over_match = false
|
||||
settings_tab = 0
|
||||
@@ -0,0 +1,7 @@
|
||||
[gd_scene load_steps=2 format=3]
|
||||
|
||||
[ext_resource type="Script" path="res://test/capture/tutorial_scene.gd" id="1"]
|
||||
|
||||
[node name="CaptureTutorial" type="Node3D"]
|
||||
script = ExtResource("1")
|
||||
step = "build"
|
||||
@@ -0,0 +1,7 @@
|
||||
[gd_scene load_steps=2 format=3]
|
||||
|
||||
[ext_resource type="Script" path="res://test/capture/tutorial_scene.gd" id="1"]
|
||||
|
||||
[node name="CaptureTutorial" type="Node3D"]
|
||||
script = ExtResource("1")
|
||||
step = "move"
|
||||
@@ -0,0 +1,50 @@
|
||||
## Capture scenario for the tutorial (A12): the real ClientSession playing the tutorial
|
||||
## offline, driven by its scripted player (TutorialPilot) until `step` begins, then held
|
||||
## there so the HUD's tutorial card shows that step's instruction and progress.
|
||||
##
|
||||
## Stages: move (just landed), build (build mode on, the ghost showing) and tide (the
|
||||
## last step, with the tide post and the line to beat).
|
||||
extends Node3D
|
||||
|
||||
const DT: float = 1.0 / Tuning.TICK_RATE_HZ
|
||||
const LIMIT_FRAMES: int = 300 * Tuning.TICK_RATE_HZ
|
||||
|
||||
@export var step: String = "move"
|
||||
@export var match_seed: int = 3
|
||||
|
||||
var _session: ClientSession
|
||||
|
||||
|
||||
func _ready() -> void:
|
||||
_session = ClientSession.new()
|
||||
_session.input.autoplay = true
|
||||
_session.play_tutorial(match_seed)
|
||||
add_child(_session)
|
||||
_session.set_process(false)
|
||||
var wanted: int = Tutorial.STEP_NAMES.find(step)
|
||||
var frames: int = 0
|
||||
while frames < LIMIT_FRAMES and _session.tutorial.step < wanted:
|
||||
_session.pump(DT)
|
||||
frames += 1
|
||||
if _session.tutorial.step != wanted:
|
||||
push_error("tutorial capture: never reached step '%s' (stopped at '%s')" % [step, _session.tutorial.step_name()])
|
||||
return
|
||||
# A moment into the step: long enough for build mode to come on, too short for the
|
||||
# script to finish it.
|
||||
for _frame: int in 6:
|
||||
_session.pump(DT)
|
||||
if _session.tutorial.step != wanted:
|
||||
push_error("tutorial capture: step '%s' was over before the picture" % step)
|
||||
return
|
||||
_session.input.map_open = false
|
||||
_session.input.buttons = 0
|
||||
_session.hud.show_state(_session.hud_state())
|
||||
_session.view.settle()
|
||||
_session._show_charts(DT)
|
||||
_session.tutorial_card.show_tutorial(_session.tutorial, true)
|
||||
|
||||
|
||||
func _process(_delta: float) -> void:
|
||||
# The session is held still; only the card is laid out again as its labels settle.
|
||||
if _session != null and _session.tutorial_card != null:
|
||||
_session.tutorial_card.show_tutorial(_session.tutorial, true)
|
||||
@@ -0,0 +1 @@
|
||||
uid://cx5rndc8jqd8d
|
||||
@@ -0,0 +1,7 @@
|
||||
[gd_scene load_steps=2 format=3]
|
||||
|
||||
[ext_resource type="Script" path="res://test/capture/tutorial_scene.gd" id="1"]
|
||||
|
||||
[node name="CaptureTutorial" type="Node3D"]
|
||||
script = ExtResource("1")
|
||||
step = "tide"
|
||||
+12
-4
@@ -32,6 +32,14 @@ func _press(screen: String, text: String) -> void:
|
||||
(buttons[text] as Button).pressed.emit()
|
||||
|
||||
|
||||
## Settings of a player who has already been offered the tutorial (A12), so the
|
||||
## program opens on the main menu.
|
||||
func _offered() -> GameSettings:
|
||||
var settings: GameSettings = GameSettings.new()
|
||||
settings.tutorial_offered = true
|
||||
return settings
|
||||
|
||||
|
||||
func _key(keycode: Key) -> InputEventKey:
|
||||
var key: InputEventKey = InputEventKey.new()
|
||||
key.physical_keycode = keycode
|
||||
@@ -79,7 +87,7 @@ func test_focus_moves_through_the_main_menu_with_the_arrow_keys() -> void:
|
||||
await tree.process_frame
|
||||
var seen: Array[String] = []
|
||||
var focused: Control = menus.get_viewport().gui_get_focus_owner()
|
||||
for _step: int in 4:
|
||||
for _step: int in 5:
|
||||
assert_not_null(focused)
|
||||
if focused == null:
|
||||
return
|
||||
@@ -89,7 +97,7 @@ func test_focus_moves_through_the_main_menu_with_the_arrow_keys() -> void:
|
||||
break
|
||||
next.grab_focus()
|
||||
focused = next
|
||||
assert_eq(seen, ["Practice against bots", "Join a server", "Settings", "Quit"] as Array[String])
|
||||
assert_eq(seen, ["Practice against bots", "Tutorial", "Join a server", "Settings", "Quit"] as Array[String])
|
||||
|
||||
|
||||
func test_rebinding_in_the_menu_detects_conflicts() -> void:
|
||||
@@ -185,7 +193,7 @@ func test_results_say_where_you_placed() -> void:
|
||||
|
||||
func test_the_shell_goes_from_the_menu_to_a_match_and_back() -> void:
|
||||
menus.free()
|
||||
var shell: AppShell = AppShell.new(GameSettings.new(), PATH)
|
||||
var shell: AppShell = AppShell.new(_offered(), PATH)
|
||||
shell.grab_mouse = false
|
||||
tree.root.add_child(shell)
|
||||
assert_eq(shell.menus.current, "main")
|
||||
@@ -220,7 +228,7 @@ func test_the_shell_goes_from_the_menu_to_a_match_and_back() -> void:
|
||||
|
||||
func test_the_shell_shows_results_when_a_match_you_played_ends() -> void:
|
||||
menus.free()
|
||||
var shell: AppShell = AppShell.new(GameSettings.new(), PATH)
|
||||
var shell: AppShell = AppShell.new(_offered(), PATH)
|
||||
shell.grab_mouse = false
|
||||
tree.root.add_child(shell)
|
||||
var rules: MatchRules = MatchRules.new()
|
||||
|
||||
Reference in New Issue
Block a user