git:20260922.c9ec6ed to git:20260927.f6a97ad

- **Types**: Use explicit types on function signatures and return values (`-> void`, etc.). Use the `class_name` type when a class has one. **Prefer `:=` for locals** to lock in the inferred type at declaration; use `var x = ...` only when you need Variant or mixed types.

- **Docs**: Use `##` comments for scene entry points or complex logic. Match the tone of nearby files.

- **Nodes**: Prefer `@onready var name: Type = $Path`.

- **Trailing pass**: If a function has no `return` statement, end the body with `pass`.

**`_` is mainly for engine callbacks** (`_ready`, `_process`, `_notification`, `_init`, etc.). **Do not prefix business methods** like `_refresh_xxx` — that clutters the file with `_` like lifecycle hooks. Use `_` on variables sparingly for internal details. GDScript has no real private; use structure and folders instead.

**Member variables**: Normal state/refs usually **no `_`** (`player`, `news_cache`). Too many `_` names hurt autocomplete and search, and look like lifecycle hooks. Use `_` only for clear implementation details (`_http_client`, `_buffer`, `_is_loading`). Official small demos often use `var _speed`; large projects do not need that pattern everywhere.

| Kind | Naming | Notes |

|------|--------|-------|

| Normal members | `player`, `ui_panel`, `news_cache` | **No** `_` prefix. |

| Internal vars | `_http_client`, `_buffer`, `_retry_count` | Implementation detail; **use sparingly**. |

| Signal handlers | `on_buy_pressed`, `on_timer_timeout`, or `handle_buy`, `handle_close` | **No** `_on_*`; keep separate from engine hooks. |

When connecting signals in `_ready`, prefer:

```gdscript

func _ready() -> void:

button.pressed.connect(on_buy_item)

pass

func on_buy_item() -> void:

pass

func refresh_ui() -> void:

update_labels()

pass

```

```gdscript

```gdscript

# Single track or playlist (auto cross-fade near end of track)

Audio.play_music("res://audio/bgm.mp3")

Audio.play_musics(["res://audio/a.mp3", "res://audio/b.mp3"])

# One-shot sound / voice

await Audio.play_voice("res://audio/narration.mp3")

# Multi-channel SFX (overlapping sounds on SoundEffect bus)

Audios.play("res://audio/click.mp3", 0.8)

```

## Animation

```gdscript

EffectAnimation2D.spawn(Vector2(500, 200), self, "res://effects/attack.png", Vector2i(4, 4), 0.5, 13)

```

## Unit tests

- Attach `zfoo/gdtest/UnitTest.gd` to a scene; it scans `.gd` files in the scene’s folder.

- In each file, every no-arg method whose name **starts or ends with `test`** (case-insensitive) is run as a unit test.

## Integration tests

- Attach `zfoo/gdtest/IntegrationTest.gd` to a scene; it scans the scene’s folder for `.tscn` whose name **starts or ends with `test`**, then runs them one by one.

- Each finished test scene must emit `gdf.events.test_passed` (UnitTest does this automatically).

- Workflow: Launch App → Check Version → Download PCK → Verify MD5 → Load PCK → Enter Game

```gdscript

# GET request

var response := await HttpHelper.async_get("https://api.example.com/data")

if response.success:

```

## Log

```gdscript

Log.info("player login uid:[{}]", user_id)

Log.error("load failed path:[{}] err:[{}]", path, err)

```

## Network

```gdscript

# `ICodec` for encode/decode

var session: Session = TcpClient.new(Codec.new(), "127.0.0.1:80")

# Register receiver (typically at login / session init)

Router.register_receiver(LoginResponse, func(packet: LoginResponse) -> void: on_login_response(packet))

Router.send(session, SomeRequest.new())

# Request–response (waits for matching reply or timeout)

var reply: LoginResponse = await Router.async_ask(session, LoginRequest.new())

```

## ResourceHelper — async loading

- Avoid blocking the main thread when loading large assets.

```gdscript

var texture: Texture2D = await ResourceHelper.async_load("res://assets/icon.svg")

var scene: PackedScene = await ResourceHelper.async_load("res://scene/Level.tscn")

```

## SceneHelper — scenes & nodes

```gdscript

# Switch scene with fade transition (default: RectTransitionFade)

await SceneHelper.async_change_scene_to_file("res://scene/Main.tscn")

# Custom slide transition

await SceneHelper.async_change_scene_to_file("res://scene/Main.tscn", RectTransitionSlide.new())

var node := SceneHelper.add_scene_to_node(load("res://scene/Popup.tscn"), self)

# Safe queue_free

SceneHelper.queue_free(old_node)

```

## SchedulerBus — delayed & periodic tasks

```gdscript

var sw := StopWatch.new() # sw.cost_seconds()

# Run once after 1000 ms

SchedulerBus.schedule(func() -> void: do_something(), 1000)

# Run every 2000 ms (optional timer name, optional sub-thread)

SchedulerBus.schedule_at_fixed_rate(func() -> void: poll_status(), 2000)

```

## Setting — persistent user config

```gdscript

Setting.set_bool("sound_enabled", true)

Setting.set_string("nickname", "player1")

Setting.save()

var enabled := Setting.get_bool("sound_enabled", false)

var name := Setting.get_string("nickname", "")

```

```gdscript

---

```gdscript

```