Stage 2: accounts, characters, permadeath, levels and experience

Identity is shaped like Steamworks so swapping to it is one subclass and no
schema change: the client presents an opaque ticket, the server validates it
into a stable 64-bit account id, and nothing downstream sees anything else.
LocalAuthProvider takes any ticket at face value -- insecure on purpose, and
labelled as such everywhere, because the point is the shape rather than the
security. Do not ship it.

Characters persist as JSON keyed by account. Account ids are written as decimal
strings because they are 64-bit and JSON numbers are doubles, which would
silently round them. A corrupt store aborts the server rather than starting
empty: starting empty looks like it worked and then saves over every character
on the first level-up.

Levels 1-15, +10 max health each, level DERIVED from lifetime experience rather
than stored beside it, so a hand-edited save cannot produce a level 12 character
with a level 3's experience. Experience is shared undivided across everyone
alive in the instance -- splitting it would make bringing a friend cost you
progress. A level-up heals by what it added, so gaining one mid-fight is relief
rather than a bar that moved further from full.

Death is permanent and unbinds the character entirely: no "return to the hub as
the character who just died", because the run is over. The record is retired,
never deleted. The five-character cap counts LIVING characters only -- counting
the dead would lock a player out of their own account after five deaths.

Verified by tools/diag_progression.tscn, which drives the real server through
kill -> xp -> level -> health and death -> retire -> roster. The bot smoke test
cannot cover that: bots are poor shots and rarely kill anything. Writing it
caught two real ordering bugs -- the death event was dispatched before the
payload that tells the player they died, and the dead character stayed bound to
the peer.

Also added --account and --store so several clients and test runs can coexist
on one machine. The smoke test now uses a scratch store; without it a rerun
resumed the previous run's characters and "a character was created" quietly
stopped being true.

193 tests. check.sh, test.sh, smoke.sh, diag_progression and diag_prediction
all pass.

tests/unit/test_character_store.gd

@@ -0,0 +1,150 @@
+extends GutTest
+## Characters and their persistence. These matter more than most tests here:
+## the whole point of a character is that it survives, and losing one to a bug
+## is not something a player can be compensated for.
+
+var store: CharacterStore
+const ACC := 1234567890123
+const OTHER := 9876543210987
+
+
+func before_each() -> void:
+	# A real file in a throwaway location, so the JSON round trip is exercised
+	# rather than mocked -- serialisation is exactly where this would break.
+	store = CharacterStore.new("user://test_characters_%d.json" % randi())
+	store.load_from_disk()
+
+
+func after_each() -> void:
+	DirAccess.remove_absolute(ProjectSettings.globalize_path(store._path))
+
+
+func test_a_new_account_has_nothing() -> void:
+	assert_eq(store.characters_for(ACC).size(), 0)
+	assert_null(store.last_played(ACC))
+	assert_true(store.can_create(ACC))
+
+
+func test_creating_and_finding_a_character() -> void:
+	var c := store.create_character(ACC, "Ada")
+	assert_not_null(c)
+	assert_eq(c.display_name, "Ada")
+	assert_eq(c.level, Progression.START_LEVEL)
+	assert_eq(c.max_hp(), SimConfig.PLAYER_MAX_HP)
+	assert_true(c.active)
+	assert_eq(store.get_character(ACC, c.id).id, c.id)
+
+
+func test_accounts_are_isolated() -> void:
+	var mine := store.create_character(ACC, "Mine")
+	store.create_character(OTHER, "Theirs")
+	assert_eq(store.characters_for(ACC).size(), 1)
+	assert_null(store.get_character(OTHER, mine.id),
+		"one account must never see another's characters")
+
+
+func test_the_living_character_limit() -> void:
+	for i in CharacterStore.MAX_ACTIVE:
+		assert_not_null(store.create_character(ACC, "c%d" % i))
+	assert_false(store.can_create(ACC))
+	assert_null(store.create_character(ACC, "one too many"))
+
+
+## The reason the cap counts living characters only: five deaths must not lock
+## a player out of their own account permanently.
+func test_retired_characters_do_not_occupy_a_slot() -> void:
+	var first := store.create_character(ACC, "doomed")
+	for i in CharacterStore.MAX_ACTIVE - 1:
+		store.create_character(ACC, "c%d" % i)
+	assert_false(store.can_create(ACC))
+	store.retire_character(ACC, first.id)
+	assert_true(store.can_create(ACC), "a death should free the slot it held")
+	assert_eq(store.characters_for(ACC).size(), CharacterStore.MAX_ACTIVE,
+		"but the record itself must still be there")
+
+
+func test_death_retires_rather_than_deletes() -> void:
+	var c := store.create_character(ACC, "Grace")
+	store.retire_character(ACC, c.id)
+	var found := store.get_character(ACC, c.id)
+	assert_not_null(found, "the record is kept for archival")
+	assert_false(found.active)
+	assert_gt(found.died_unix, 0, "and records when it happened")
+
+
+func test_last_played_prefers_the_last_one_and_skips_the_dead() -> void:
+	var a := store.create_character(ACC, "A")
+	var b := store.create_character(ACC, "B")
+	store.set_last_played(ACC, a.id)
+	assert_eq(store.last_played(ACC).id, a.id)
+	store.retire_character(ACC, a.id)
+	assert_eq(store.last_played(ACC).id, b.id,
+		"a dead character must not be auto-selected on login")
+
+
+func test_everything_survives_a_save_and_reload() -> void:
+	var c := store.create_character(ACC, "Persistent")
+	store.grant_xp(ACC, c.id, Progression.xp_to_next(1) + 5)
+	store.set_last_played(ACC, c.id)
+	var dead := store.create_character(ACC, "Departed")
+	store.retire_character(ACC, dead.id)
+
+	var reloaded := CharacterStore.new(store._path)
+	assert_true(reloaded.load_from_disk())
+	var got := reloaded.get_character(ACC, c.id)
+	assert_not_null(got, "the character survived the round trip")
+	assert_eq(got.display_name, "Persistent")
+	assert_eq(got.level, 2)
+	assert_eq(got.colour.to_html(false), c.colour.to_html(false))
+	assert_eq(reloaded.last_played(ACC).id, c.id)
+	assert_false(reloaded.get_character(ACC, dead.id).active,
+		"and so did the fact that one of them died")
+
+
+## Account ids are 64-bit; JSON numbers are doubles and would round them. They
+## are written as decimal strings for exactly this reason.
+func test_large_account_ids_survive_the_round_trip() -> void:
+	var big := 9007199254740993
+	store.create_character(big, "Precise")
+	var reloaded := CharacterStore.new(store._path)
+	reloaded.load_from_disk()
+	assert_eq(reloaded.characters_for(big).size(), 1,
+		"a 64-bit account id must not be mangled by JSON")
+
+
+func test_a_corrupt_file_is_refused_rather_than_overwritten() -> void:
+	assert_not_null(store.create_character(ACC, "Valuable"))
+	var f := FileAccess.open(store._path, FileAccess.WRITE)
+	f.store_string("{ this is not json")
+	f.close()
+	var reloaded := CharacterStore.new(store._path)
+	assert_false(reloaded.load_from_disk(),
+		"a bad file must fail loudly; silently starting empty would then " +
+		"save over every character on the next write")
+
+
+func test_granting_experience_reports_levels_gained() -> void:
+	var c := store.create_character(ACC, "Riser")
+	assert_eq(store.grant_xp(ACC, c.id, 1), 0, "not enough for a level")
+	assert_gte(store.grant_xp(ACC, c.id, Progression.total_xp_for_level(3)), 1,
+		"crossing a threshold reports the levels")
+	var after := store.get_character(ACC, c.id)
+	assert_eq(after.level, Progression.level_for_xp(after.total_xp),
+		"level and experience must never disagree")
+
+
+func test_a_dead_character_earns_nothing() -> void:
+	var c := store.create_character(ACC, "Late")
+	store.retire_character(ACC, c.id)
+	store.grant_xp(ACC, c.id, 5000)
+	assert_eq(store.get_character(ACC, c.id).total_xp, 0)
+
+
+## Names are shown to other players, so they are clamped at the boundary rather
+## than trusted anywhere downstream.
+func test_names_are_sanitised() -> void:
+	assert_eq(Character.sanitize_name("   "), "adventurer", "blank names get a default")
+	assert_lte(Character.sanitize_name("x".repeat(500)).length(), Character.MAX_NAME)
+	var with_control := "ab" + String.chr(7) + String.chr(10) + "cd"
+	assert_eq(Character.sanitize_name(with_control), "abcd",
+		"control characters would let a name break the HUD's layout")

tests/unit/test_character_store.gd.uid

@@ -0,0 +1 @@
+uid://dxdd52gmk2ki4

tests/unit/test_net_codec.gd

@@ -161,3 +161,60 @@ func test_cleared_countdown_round_trips() -> void:
 func test_countdown_defaults_to_not_applicable() -> void:
 	var snap := NetCodec.decode_snapshot(NetCodec.encode_snapshot(world))
 	assert_eq(int(snap["cleared_countdown"]), Protocol.COUNTDOWN_NONE)
+
+
+# --- Characters -------------------------------------------------------------
+
+func test_character_roster_round_trips() -> void:
+	var rng := RandomNumberGenerator.new()
+	rng.seed = 5
+	var a := Character.create("Ada", rng)
+	a.grant_xp(Progression.total_xp_for_level(4))
+	var b := Character.create("Departed", rng)
+	b.retire()
+	var out := NetCodec.decode_characters(
+		NetCodec.encode_characters([a, b] as Array[Character], a.id))
+	assert_eq(String(out["selected"]), a.id)
+	var chars: Array = out["characters"]
+	assert_eq(chars.size(), 2)
+	assert_eq(String(chars[0]["name"]), "Ada")
+	assert_eq(int(chars[0]["level"]), a.level)
+	assert_eq(int(chars[0]["max_hp"]), a.max_hp(),
+		"the roster shows each character's own health ceiling")
+	assert_true(chars[0]["active"])
+	assert_false(chars[1]["active"], "a dead character is listed, not hidden")
+
+
+## Colour is a character's only identity until cosmetics exist, so it has to
+## survive the wire exactly rather than approximately.
+func test_character_colour_survives_the_wire() -> void:
+	var rng := RandomNumberGenerator.new()
+	rng.seed = 11
+	var c := Character.create("Hue", rng)
+	var out := NetCodec.decode_characters(
+		NetCodec.encode_characters([c] as Array[Character], ""))
+	var got: Color = out["characters"][0]["colour"]
+	assert_eq(got.to_rgba32(), c.colour.to_rgba32())
+
+
+func test_an_empty_character_list_is_safe() -> void:
+	var out := NetCodec.decode_characters(
+		NetCodec.encode_characters([] as Array[Character], ""))
+	assert_eq((out["characters"] as Array).size(), 0)
+	assert_eq(NetCodec.decode_characters(PackedByteArray())["characters"].size(), 0)
+
+
+## Max health is per-character now, so a snapshot that assumed a constant would
+## draw every levelled player's bar wrong.
+func test_the_snapshot_carries_each_players_own_max_health() -> void:
+	var p: SimPlayer = world.players[42]
+	p.level = 5
+	p.max_hp = Progression.max_hp_for_level(5)
+	p.hp = 42
+	p.colour = Color(0.2, 0.6, 0.9)
+	var snap := NetCodec.decode_snapshot(NetCodec.encode_snapshot(world))
+	var rec: Dictionary = snap["players"][0]
+	assert_eq(int(rec["hp"]), 42)
+	assert_eq(int(rec["max_hp"]), Progression.max_hp_for_level(5))
+	assert_almost_eq((rec["colour"] as Color).b, 0.9, 0.02,
+		"party members are told apart by colour, so it rides the snapshot")

tests/unit/test_progression.gd

@@ -0,0 +1,78 @@
+extends GutTest
+## The XP curve and what a level is worth. Pure arithmetic, so the shape of
+## progression can be argued about without running a server.
+
+
+func test_level_one_is_the_base_health() -> void:
+	assert_eq(Progression.max_hp_for_level(1), SimConfig.PLAYER_MAX_HP)
+
+
+func test_each_level_adds_ten_health() -> void:
+	for level in range(1, Progression.MAX_LEVEL):
+		assert_eq(Progression.max_hp_for_level(level + 1)
+			- Progression.max_hp_for_level(level), Progression.HP_PER_LEVEL)
+
+
+func test_the_cap_is_reachable_and_final() -> void:
+	assert_eq(Progression.max_hp_for_level(Progression.MAX_LEVEL),
+		SimConfig.PLAYER_MAX_HP + (Progression.MAX_LEVEL - 1) * Progression.HP_PER_LEVEL)
+	# Past the cap nothing further is gained, however much xp arrives.
+	assert_eq(Progression.max_hp_for_level(999),
+		Progression.max_hp_for_level(Progression.MAX_LEVEL))
+	assert_eq(Progression.xp_to_next(Progression.MAX_LEVEL), 0)
+
+
+func test_level_is_derived_consistently_from_experience() -> void:
+	# The two directions must agree exactly, or a character's level could
+	# disagree with the experience that earned it.
+	for level in range(1, Progression.MAX_LEVEL + 1):
+		var at := Progression.total_xp_for_level(level)
+		assert_eq(Progression.level_for_xp(at), level,
+			"exactly enough xp for level %d should be level %d" % [level, level])
+		# Skipped at level 1: there is no level 0 to fall short into, and
+		# negative lifetime xp is not a state a character can be in.
+		if level > Progression.START_LEVEL:
+			assert_eq(Progression.level_for_xp(at - 1), level - 1,
+				"one short of level %d should still be level %d" % [level, level - 1])
+
+
+func test_experience_never_exceeds_the_cap() -> void:
+	assert_eq(Progression.level_for_xp(99999999), Progression.MAX_LEVEL)
+	assert_eq(Progression.level_progress(99999999), 1.0,
+		"a capped character's bar should read full, not empty")
+
+
+func test_progress_runs_from_zero_to_one_within_a_level() -> void:
+	var at := Progression.total_xp_for_level(3)
+	assert_almost_eq(Progression.level_progress(at), 0.0, 0.001)
+	assert_almost_eq(Progression.level_progress(at + Progression.xp_to_next(3) / 2), 0.5, 0.05)
+
+
+func test_the_requirement_grows_with_level() -> void:
+	for level in range(1, Progression.MAX_LEVEL - 1):
+		assert_gt(Progression.xp_to_next(level + 1), Progression.xp_to_next(level),
+			"later levels must cost more, or the curve is flat at the end")
+
+
+## The brief's one concrete pacing requirement: a first full clear should be a
+## bit more than the first level-up needs.
+func test_a_first_full_dungeon_clear_slightly_exceeds_the_first_level() -> void:
+	# A depth-1 dungeon holds roughly a dozen enemies plus the boss.
+	var trash := 12 * Progression.xp_for_enemy(Content.ENEMY_DRIFTER)
+	var clear := trash + Progression.xp_for_boss(Content.BOSS_WARDEN)
+	var needed := Progression.xp_to_next(1)
+	assert_gt(clear, needed, "a full clear should get you the first level")
+	assert_lt(clear, needed * 2,
+		"but not two levels, or the first run outpaces the curve")
+
+
+func test_unknown_enemies_award_nothing_rather_than_a_default() -> void:
+	assert_eq(Progression.xp_for_enemy(&"no_such_enemy"), 0)
+	assert_eq(Progression.xp_for_enemy(Content.ENEMY_DUMMY), 0,
+		"the practice target must not be an xp farm")
+
+
+func test_experience_below_the_first_level_is_still_level_one() -> void:
+	assert_eq(Progression.level_for_xp(0), Progression.START_LEVEL)
+	assert_eq(Progression.level_for_xp(-500), Progression.START_LEVEL,
+		"a nonsensical total must clamp rather than produce a level 0 character")

tests/unit/test_progression.gd.uid

@@ -0,0 +1 @@
+uid://cllapwggk4ean