feat: implement DEV-1 boot verification

This commit is contained in:
2026-08-17 14:57:07 +08:00
parent d200304101
commit ed8f7e71e6
10 changed files with 435 additions and 9 deletions
+4 -5
View File
@@ -14,7 +14,7 @@
## Current State
- Stage: `HANDDRAWN_ENTRY_FLOW_APPROVED`
- Active implementation step: `DEV-1A_IN_PROGRESS`
- Active implementation step: `DEV-1B_IN_PROGRESS`
- Planning baseline: `d59555c5a3cf95fc44de79ba06c02e650eb3df3b`
- Documentation consolidation baseline:
`53824d2394e7facdc8dca19aa20a690a5c960aca`
@@ -43,7 +43,6 @@
## Next Action
Implement and narrowly verify `DEV-1A`: real Godot Boot, named local resource/
settings/save verification, recoverable error and Retry. Keep every later
DEV-1 substep and all later gameplay pages frozen until the Boot boundary is
committed and pushed.
Implement and narrowly verify `DEV-1B`: persistent first-launch language, safe
area, text scale, reduced motion/flashes and captions. Keep later DEV-1
substeps and all gameplay pages frozen until setup is committed and pushed.
+14 -4
View File
@@ -432,7 +432,7 @@ until that entry path is runnable, verified, committed and pushed.
## FG-4 Japanese 2D Hand-Drawn Redevelopment Plan
> Status: `OWNER_APPROVED`
> Active implementation step: `DEV-1A_IN_PROGRESS`
> Active implementation step: `DEV-1B_IN_PROGRESS`
> Goal: `06_DEVELOPMENT_AND_REVIEW.md`
> Contract: `06_DEVELOPMENT_AND_REVIEW.md`
> Page plan: `03_PAGES_AND_UX.md`
@@ -491,8 +491,8 @@ Only one row may be `IN_PROGRESS`. A failed check keeps that row active.
| Substep | Status | Owned product boundary | Narrow acceptance check | Commit boundary |
| --- | --- | --- | --- | --- |
| `DEV-1A` SYS-001 Boot | `IN_PROGRESS` | New entry controller, resource/settings/save verification, named progress, recoverable error, Retry and safe diagnostics | Fresh boot reaches setup/title; injected missing resource remains branded and Retry restores the same verification operation | Focused Boot implementation, test, plan/checkpoint update and push |
| `DEV-1B` SYS-002 First launch | `PENDING` | Persistent language, safe area, 100/115/130% text, reduced motion/flashes, captions and usable first-launch completion | First launch cannot bypass Apply; applied setup survives restart and no longer appears forcibly; reset fixture restores it | Focused setup implementation, persistence/layout test, plan/checkpoint update and push |
| `DEV-1A` SYS-001 Boot | `COMPLETE` | New entry controller, resource/settings/save verification, named progress, recoverable error, Retry and safe diagnostics | `ABG_DEV1_BOOT_OK`; `ABG_DEV1_BOOT_RUNTIME_OK`; strict attempt runner PASS | Focused Boot implementation, test, plan/checkpoint update and push |
| `DEV-1B` SYS-002 First launch | `IN_PROGRESS` | Persistent language, safe area, 100/115/130% text, reduced motion/flashes, captions and usable first-launch completion | First launch cannot bypass Apply; applied setup survives restart and no longer appears forcibly; reset fixture restores it | Focused setup implementation, persistence/layout test, plan/checkpoint update and push |
| `DEV-1C` SYS-003 Title | `PENDING` | Painted guild-threshold Title, truthful New Game/Continue/Settings/Credits state and exact return/back behavior | No-run and resumable fixtures show correct enabled states; disabled activation gives a visible reason; child pages return to Title | Focused Title implementation, state/navigation test, plan/checkpoint update and push |
| `DEV-1D` SET-001..006 + SYS-008 | `PENDING` | Settings index, display/text, motion/flash/power, audio/captions, controls, language/locale, credits/licenses/data notice | Every visible control changes real persisted state or exposes a precise unavailable reason; Apply/Discard and exact caller return pass | Focused Settings/Credits implementation, behavior/localization test, plan/checkpoint update and push |
| `DEV-1E` Entry-flow candidate | `PENDING` | End-to-end player order, responsive refinement, restart/reset fixtures and candidate evidence | Boot-to-Title real input path; 760x360, 844x390, 1280x720; English/Chinese; 100/130%; reduced modes; normal rendering; full applicable regression; strict diagnostics | Candidate docs/evidence closure commit and push |
@@ -523,7 +523,7 @@ package, store and release gates remain `OPEN`.
| ID | Status | Boundary |
| --- | --- | --- |
| `DEV1-I01` | `OPEN_DEV-1A` | Historical facade combines entry and later gameplay; DEV-1 needs a bounded entry controller without changing preserved gameplay systems. |
| `DEV1-I01` | `RESOLVED_DEV-1A` | A bounded entry controller now owns Boot while the historical gameplay facade remains preserved and hidden during normal launch. |
| `DEV1-I02` | `RESOLVED_REUSE` | Existing `p9_3_guild_hall.png` is a usable hand-drawn entry background; no DEV-1 paid image request is currently required. |
| `DEV1-I03` | `OPEN_HUMAN` | Owner visual and comprehension acceptance must remain open after local runtime review. |
@@ -587,3 +587,13 @@ they are not duplicated here.
content remain ordered follow-up steps rather than parallel work.
- One HAPI development session works directly in the current repository and
branch; no multi-Agent or new worktree is authorized.
### 2026-08-17 - DEV-1A Boot Implemented
- Normal launch now enters a bounded Godot entry shell over the existing
hand-drawn guild threshold; the historical gameplay facade remains preserved.
- Boot verifies required local resources, user storage, settings data and the
current save envelope with named progress. Unsafe data is not reset.
- Recoverable failure retains the branded screen, a stable non-path diagnostic
and Retry. Focused service and real-main-scene tests pass with strict markers
`ABG_DEV1_BOOT_OK` and `ABG_DEV1_BOOT_RUNTIME_OK`.
+99
View File
@@ -0,0 +1,99 @@
class_name ABGEntryBootService
extends RefCounted
const DEFAULT_REQUIRED_RESOURCES: Array[String] = [
"res://main.tscn",
"res://entry/entry_shell.gd",
"res://assets/backgrounds/p9_3_guild_hall.png",
"res://assets/fonts/NotoSansSC.ttf",
]
const DEFAULT_PREFERENCES_PATH := "user://aetherbound_guild_settings.json"
const DEFAULT_SAVE_PATH := "user://aetherbound_guild_p10_3.json"
var required_resources: Array = DEFAULT_REQUIRED_RESOURCES.duplicate()
var preferences_path := DEFAULT_PREFERENCES_PATH
var save_path := DEFAULT_SAVE_PATH
var checks: Array[Dictionary] = []
var index := 0
var result: Dictionary = {}
func begin() -> Dictionary:
checks = []
for path in required_resources:
checks.append({"kind": "resource", "path": path})
checks.append({"kind": "storage"})
checks.append({"kind": "preferences", "path": preferences_path})
checks.append({"kind": "save", "path": save_path})
index = 0
result = {
"state": "running",
"completed": 0,
"total": checks.size(),
"step": "resources",
"code": "",
}
return result.duplicate(true)
func verify_next() -> Dictionary:
if checks.is_empty():
begin()
if String(result.get("state", "")) != "running":
return result.duplicate(true)
if index >= checks.size():
result["state"] = "complete"
result["step"] = "complete"
return result.duplicate(true)
var check: Dictionary = checks[index]
var check_result := _run_check(check)
if not check_result.ok:
result = {
"state": "error",
"completed": index,
"total": checks.size(),
"step": String(check_result.step),
"code": String(check_result.code),
}
return result.duplicate(true)
index += 1
result["completed"] = index
result["step"] = _next_step()
if index >= checks.size():
result["state"] = "complete"
result["step"] = "complete"
return result.duplicate(true)
func _run_check(check: Dictionary) -> Dictionary:
match String(check.kind):
"resource":
var path := String(check.path)
if not ResourceLoader.exists(path) or ResourceLoader.load(path) == null:
return {"ok": false, "step": "resources", "code": "REQUIRED_RESOURCE_UNAVAILABLE"}
"storage":
var user_root := ProjectSettings.globalize_path("user://")
if DirAccess.open(user_root) == null:
return {"ok": false, "step": "storage", "code": "LOCAL_STORAGE_UNAVAILABLE"}
"preferences":
if FileAccess.file_exists(String(check.path)):
var preferences_parser := JSON.new()
var preferences_error := preferences_parser.parse(FileAccess.get_file_as_string(String(check.path)))
if preferences_error != OK or not preferences_parser.data is Dictionary:
return {"ok": false, "step": "preferences", "code": "SETTINGS_FILE_INVALID"}
"save":
if FileAccess.file_exists(String(check.path)):
var save_parser := JSON.new()
var save_error := save_parser.parse(FileAccess.get_file_as_string(String(check.path)))
var parsed = save_parser.data
if save_error != OK or not parsed is Dictionary or not parsed.has("save_kind") or not parsed.has("save_version"):
return {"ok": false, "step": "save", "code": "SAVE_REVIEW_REQUIRED"}
return {"ok": true, "step": String(check.kind), "code": ""}
func _next_step() -> String:
if index >= checks.size():
return "complete"
return String(checks[index].kind)
+1
View File
@@ -0,0 +1 @@
uid://bs0l0l4xkubt8
+174
View File
@@ -0,0 +1,174 @@
class_name ABGEntryShell
extends Control
const BootService = preload("res://entry/boot_service.gd")
const GUILD_BACKGROUND = preload("res://assets/backgrounds/p9_3_guild_hall.png")
const UI_FONT = preload("res://assets/fonts/NotoSansSC.ttf")
signal boot_completed
@export var auto_start := true
var boot_service := BootService.new()
var boot_snapshot: Dictionary = {}
var boot_generation := 0
var status_label: Label
var detail_label: Label
var progress_bar: ProgressBar
var retry_button: Button
var diagnostics_label: Label
func _ready() -> void:
set_anchors_and_offsets_preset(Control.PRESET_FULL_RECT)
_build_boot_screen()
if auto_start:
call_deferred("start_boot")
func start_boot() -> void:
boot_generation += 1
var generation := boot_generation
boot_snapshot = boot_service.begin()
_render_boot_state()
while generation == boot_generation and String(boot_snapshot.state) == "running":
await get_tree().process_frame
boot_snapshot = boot_service.verify_next()
_render_boot_state()
if generation == boot_generation and String(boot_snapshot.state) == "complete":
await get_tree().create_timer(0.18).timeout
if generation == boot_generation:
boot_completed.emit()
_show_next_step_hold()
func retry_boot() -> void:
if String(boot_snapshot.get("state", "")) != "error":
return
start_boot()
func _build_boot_screen() -> void:
for child in get_children():
child.queue_free()
var background := TextureRect.new()
background.name = "EntryBackground"
background.texture = GUILD_BACKGROUND
background.expand_mode = TextureRect.EXPAND_IGNORE_SIZE
background.stretch_mode = TextureRect.STRETCH_KEEP_ASPECT_COVERED
background.set_anchors_and_offsets_preset(Control.PRESET_FULL_RECT)
background.mouse_filter = Control.MOUSE_FILTER_IGNORE
add_child(background)
var shade := ColorRect.new()
shade.name = "EntryShade"
shade.color = Color(0.035, 0.07, 0.10, 0.40)
shade.set_anchors_and_offsets_preset(Control.PRESET_FULL_RECT)
shade.mouse_filter = Control.MOUSE_FILTER_IGNORE
add_child(shade)
var safe := MarginContainer.new()
safe.name = "EntrySafeArea"
safe.set_anchors_and_offsets_preset(Control.PRESET_FULL_RECT)
safe.add_theme_constant_override("margin_left", 56)
safe.add_theme_constant_override("margin_right", 56)
safe.add_theme_constant_override("margin_top", 40)
safe.add_theme_constant_override("margin_bottom", 40)
add_child(safe)
var layout := VBoxContainer.new()
layout.name = "BootLayout"
layout.alignment = BoxContainer.ALIGNMENT_END
layout.add_theme_constant_override("separation", 10)
safe.add_child(layout)
var identity := Label.new()
identity.name = "BootIdentity"
identity.text = "AETHERBOUND GUILD"
identity.add_theme_font_override("font", UI_FONT)
identity.add_theme_font_size_override("font_size", 34)
identity.add_theme_color_override("font_color", Color("#f3f6f2"))
identity.add_theme_color_override("font_shadow_color", Color(0.05, 0.08, 0.10, 0.8))
identity.add_theme_constant_override("shadow_offset_x", 2)
identity.add_theme_constant_override("shadow_offset_y", 2)
layout.add_child(identity)
status_label = Label.new()
status_label.name = "BootStatus"
status_label.add_theme_font_override("font", UI_FONT)
status_label.add_theme_font_size_override("font_size", 20)
status_label.add_theme_color_override("font_color", Color("#f3f6f2"))
layout.add_child(status_label)
detail_label = Label.new()
detail_label.name = "BootDetail"
detail_label.add_theme_font_override("font", UI_FONT)
detail_label.add_theme_font_size_override("font_size", 16)
detail_label.add_theme_color_override("font_color", Color("#d7e0dd"))
detail_label.autowrap_mode = TextServer.AUTOWRAP_WORD_SMART
layout.add_child(detail_label)
progress_bar = ProgressBar.new()
progress_bar.name = "BootProgress"
progress_bar.custom_minimum_size = Vector2(420, 12)
progress_bar.size_flags_horizontal = Control.SIZE_SHRINK_BEGIN
progress_bar.show_percentage = false
layout.add_child(progress_bar)
retry_button = Button.new()
retry_button.name = "BootRetry"
retry_button.text = "Retry verification"
retry_button.custom_minimum_size = Vector2(240, 52)
retry_button.size_flags_horizontal = Control.SIZE_SHRINK_BEGIN
retry_button.add_theme_font_override("font", UI_FONT)
retry_button.add_theme_font_size_override("font_size", 18)
retry_button.pressed.connect(retry_boot)
layout.add_child(retry_button)
diagnostics_label = Label.new()
diagnostics_label.name = "BootDiagnostics"
diagnostics_label.add_theme_font_override("font", UI_FONT)
diagnostics_label.add_theme_font_size_override("font_size", 14)
diagnostics_label.add_theme_color_override("font_color", Color("#ffd4d4"))
layout.add_child(diagnostics_label)
func _render_boot_state() -> void:
if status_label == null:
return
var state := String(boot_snapshot.get("state", "running"))
var step := String(boot_snapshot.get("step", "resources"))
progress_bar.max_value = max(1, int(boot_snapshot.get("total", 1)))
progress_bar.value = int(boot_snapshot.get("completed", 0))
retry_button.visible = state == "error"
diagnostics_label.visible = state == "error"
match state:
"error":
status_label.text = "Verification needs attention"
detail_label.text = "Local data was left unchanged. Resolve the issue, then retry this check."
diagnostics_label.text = "Diagnostic: %s" % String(boot_snapshot.get("code", "UNKNOWN"))
"complete":
status_label.text = "Local verification complete"
detail_label.text = "Resources, settings storage and save access are ready."
diagnostics_label.text = ""
_:
status_label.text = "Preparing the guild threshold"
detail_label.text = _step_text(step)
diagnostics_label.text = ""
func _step_text(step: String) -> String:
match step:
"resources": return "Checking required local resources..."
"storage": return "Checking local storage access..."
"preferences": return "Checking display and accessibility settings..."
"save": return "Checking the latest local run record..."
return "Completing local verification..."
func _show_next_step_hold() -> void:
status_label.text = "First-launch setup"
detail_label.text = "Language, safe area and accessibility setup will open next."
progress_bar.visible = false
retry_button.visible = false
diagnostics_label.visible = false
+1
View File
@@ -0,0 +1 @@
uid://drbf3khvt30f2
+12
View File
@@ -23,6 +23,7 @@ const P103StateScript = preload("res://p10_3/run_state.gd")
const P103SaveServiceScript = preload("res://p10_3/save_v9_service.gd")
const FG2RuntimeControllerScript = preload("res://campaign/fg2_graybox_controller.gd")
const FG2FixtureScript = preload("res://campaign/fg2_fixture.gd")
const EntryShellScript = preload("res://entry/entry_shell.gd")
const AppPage = FacadeScript.AppPage
const ANIMATION_SPECS = FacadeScript.ANIMATION_SPECS
const BATTLE_PHASE_DURATIONS = FacadeScript.BATTLE_PHASE_DURATIONS
@@ -63,6 +64,7 @@ var p102_handoff_button: Button
var p103_experience
var p103_handoff_pending := false
var p103_handoff_button: Button
var entry_shell
var active_battle_feedback:
get: return facade.active_battle_feedback
@@ -237,6 +239,9 @@ var victory_events:
set(value): facade.victory_events = value
func _ready() -> void:
var should_start_entry: bool = auto_boot and not OS.has_feature("fg2_review")
if should_start_entry:
facade.auto_boot = false
var should_start_fg2: bool = auto_boot and (fg2_review_enabled or OS.has_feature("fg2_review"))
var p103_resume_snapshot: Dictionary = _p103_resume_snapshot() if p100_persistence_enabled and not should_start_fg2 else {}
var should_start_p103: bool = auto_boot and p100_experience_enabled and not p103_resume_snapshot.is_empty()
@@ -258,6 +263,13 @@ func _ready() -> void:
facade.set_anchors_and_offsets_preset(Control.PRESET_FULL_RECT)
add_child(facade)
theme = facade.theme
if should_start_entry:
facade.visible = false
entry_shell = EntryShellScript.new()
entry_shell.name = "EntryShell"
entry_shell.set_anchors_and_offsets_preset(Control.PRESET_FULL_RECT)
add_child(entry_shell)
return
facade.authoritative_battle_requested.connect(start_authoritative_battle)
authoritative_battle_presenter = P92BattlePresenterScript.new(self)
if should_start_fg2:
+38
View File
@@ -0,0 +1,38 @@
extends SceneTree
const MainScene = preload("res://main.tscn")
var failures: Array[String] = []
func _initialize() -> void:
call_deferred("run_test")
func run_test() -> void:
var game := MainScene.instantiate()
root.add_child(game)
for frame in range(40):
await process_frame
var shell = game.get_node_or_null("EntryShell")
expect(shell != null, "main scene creates the DEV-1 entry shell")
expect(not game.facade.visible, "historical gameplay facade stays preserved and hidden")
if shell != null:
expect(String(shell.boot_snapshot.get("state", "")) == "complete", "real entry reaches a completed verification")
expect(shell.get_node("EntrySafeArea/BootLayout/BootStatus").text == "First-launch setup", "completed Boot hands off toward first-launch setup")
expect(not shell.get_node("EntrySafeArea/BootLayout/BootRetry").visible, "Retry is hidden after success")
game.queue_free()
for frame in range(20):
await process_frame
if failures.is_empty():
print("ABG_DEV1_BOOT_RUNTIME_OK entry_shell=true facade_hidden=true boot_complete=true handoff=first_launch")
quit(0)
else:
for failure in failures:
push_error(failure)
quit(1)
func expect(condition: bool, message: String) -> void:
if not condition:
failures.append("DEV-1 Boot runtime: %s" % message)
+91
View File
@@ -0,0 +1,91 @@
extends SceneTree
const BootService = preload("res://entry/boot_service.gd")
const SETTINGS_PATH := "user://dev1_boot_settings_test.json"
const SAVE_PATH := "user://dev1_boot_save_test.json"
var failures: Array[String] = []
func _initialize() -> void:
call_deferred("run_test")
func run_test() -> void:
_cleanup()
verify_clean_boot()
verify_recoverable_resource_retry()
verify_settings_and_save_diagnostics()
_cleanup()
if failures.is_empty():
print("ABG_DEV1_BOOT_OK resources=true storage=true settings=true save=true recoverable_retry=true diagnostics=safe")
quit(0)
else:
for failure in failures:
push_error(failure)
quit(1)
func verify_clean_boot() -> void:
var service: RefCounted = _service()
var terminal := _run(service)
expect(terminal.state == "complete", "clean install reaches complete: %s" % str(terminal))
expect(terminal.completed == terminal.total, "complete counts every named check")
func verify_recoverable_resource_retry() -> void:
var service: RefCounted = _service()
service.required_resources = ["res://entry/not-present.tres"]
var failed := _run(service)
expect(failed.state == "error" and failed.code == "REQUIRED_RESOURCE_UNAVAILABLE", "missing resource is recoverable and coded")
expect(not failed.has("path"), "player diagnostic does not expose a local path")
service.required_resources = ["res://entry/entry_shell.gd"]
var retried := _run(service)
expect(retried.state == "complete", "retry re-runs the verification operation")
func verify_settings_and_save_diagnostics() -> void:
_write(SETTINGS_PATH, "not-json")
var settings_failure := _run(_service())
expect(settings_failure.code == "SETTINGS_FILE_INVALID", "invalid settings block with a stable diagnostic")
_cleanup()
_write(SAVE_PATH, JSON.stringify({"unexpected": true}))
var save_failure := _run(_service())
expect(save_failure.code == "SAVE_REVIEW_REQUIRED", "unsafe save requires review rather than reset")
func _service() -> RefCounted:
var service: RefCounted = BootService.new()
service.required_resources = [
"res://main.tscn",
"res://entry/entry_shell.gd",
"res://assets/backgrounds/p9_3_guild_hall.png",
]
service.preferences_path = SETTINGS_PATH
service.save_path = SAVE_PATH
return service
func _run(service: RefCounted) -> Dictionary:
var snapshot: Dictionary = service.begin()
while snapshot.state == "running":
snapshot = service.verify_next()
return snapshot
func _write(path: String, text: String) -> void:
var file := FileAccess.open(path, FileAccess.WRITE)
file.store_string(text)
file.close()
func _cleanup() -> void:
for path in [SETTINGS_PATH, SAVE_PATH]:
if FileAccess.file_exists(path):
DirAccess.remove_absolute(path)
func expect(condition: bool, message: String) -> void:
if not condition:
failures.append("DEV-1 Boot: %s" % message)
@@ -0,0 +1 @@
uid://xmraqg0abti2