让游戏可调：把数值从代码里抠出来

先感受一下

下面这个 demo 里，那段 JSON 不是装饰。你改一个数字点「应用」，下面那个角色的物理立刻就变了 —— 它真的在解析那段配置。

试试把 gravity 改成 600，或者点一下「月球重力」。

迭代速度是一个设计指标

算一笔账。假设你在调跳跃手感：

最后一行才是重点。迭代成本高的时候，人会不自觉地降低标准 —— 不是因为懒，是因为每一次尝试都很贵，你会在「还行」的时候停下。

三个层次，成本递增

层次一：@export（十分钟，覆盖 80% 需求）

最低成本的做法，而且 Godot 原生支持。把常量改成导出变量：

extends CharacterBody2D

@export_group("基础物理")
@export var max_run: float = 112.0
@export var jump_speed: float = 340.0
@export var gravity: float = 1500.0

@export_group("宽容窗口")
@export_range(0.0, 0.3, 0.01) var coyote_time: float = 0.10
@export_range(0.0, 0.3, 0.01) var buffer_time: float = 0.12

@export_group("跳跃曲线")
@export_range(0.1, 1.0, 0.05) var cut_mult: float = 0.45
@export_range(1.0, 3.0, 0.05) var fall_mult: float = 1.55

层次二：Resource 文件（半小时）

当参数需要被多个对象共享、或者需要多套配置切换时，升级到 Resource。

class_name MovementProfile
extends Resource

@export var max_run: float = 112.0
@export var jump_speed: float = 340.0
@export var gravity: float = 1500.0
@export_range(0.0, 0.3, 0.01) var coyote_time: float = 0.10
@export_range(0.0, 0.3, 0.01) var buffer_time: float = 0.12
@export_range(0.1, 1.0, 0.05) var cut_mult: float = 0.45
@export_range(1.0, 3.0, 0.05) var fall_mult: float = 1.55

extends CharacterBody2D

@export var profile: MovementProfile

func _physics_process(delta: float) -> void:
	var g := profile.gravity
	if velocity.y > 0.0:
		g *= profile.fall_mult
	velocity.y += g * delta
	# ……

好处：

• 你可以存好几个 .tres 文件：normal.tres、underwater.tres、ice.tres，运行时切换就能做出水下 / 冰面的不同手感
• 不同的角色可以共享或各用一套
• 它是纯数据文件，能被 git diff 看懂（比场景文件友好得多）

层次三：外部文件 + 热重载（一两小时）

最高一档：把配置放在游戏之外的 JSON / CSV 文件里，游戏运行时监视文件变化，一改就重新加载。

extends Node          # autoload: Tuning

const PATH := "res://config/tuning.json"

var data: Dictionary = {}
var _last_mtime: int = 0

func _ready() -> void:
	_load()

func _process(_delta: float) -> void:
	# 只在编辑器 / 调试构建里做文件监视，发布版不需要
	if not OS.is_debug_build():
		return
	var mtime := FileAccess.get_modified_time(PATH)
	if mtime != _last_mtime:
		_load()
		reloaded.emit()

signal reloaded

func _load() -> void:
	_last_mtime = FileAccess.get_modified_time(PATH)
	var f := FileAccess.open(PATH, FileAccess.READ)
	if f == null:
		push_error("读不到配置：%s" % PATH)
		return
	var parsed = JSON.parse_string(f.get_as_text())
	if typeof(parsed) != TYPE_DICTIONARY:
		push_error("配置不是合法 JSON，保留上一份")   # ← 关键：别把游戏搞崩
		return
	data = parsed

func get_num(path: String, fallback: float) -> float:
	var node: Variant = data
	for key in path.split("."):
		if typeof(node) != TYPE_DICTIONARY or not node.has(key):
			return fallback         # ← 缺键就用默认值，不报错
		node = node[key]
	return float(node) if typeof(node) in [TYPE_FLOAT, TYPE_INT] else fallback

调试面板：让调参发生在游戏里

比外部文件更进一步的做法：在游戏里直接放一个调参面板，按 F1 呼出。

这听起来很奢侈，但在 Godot 里成本很低 —— 而且它有一个外部文件比不了的优势：你在玩的同时就能调，手不用离开。

extends CanvasLayer          # autoload: DebugPanel

var _target: Object = null
var _props: Array[Dictionary] = []

func watch(obj: Object, prop: String, from: float, to: float) -> void:
	_props.append({ "obj": obj, "prop": prop, "from": from, "to": to })
	_rebuild()

func _unhandled_input(e: InputEvent) -> void:
	if e is InputEventKey and e.pressed and e.keycode == KEY_F1:
		visible = not visible

func _rebuild() -> void:
	for c in $Panel/VBox.get_children():
		c.queue_free()
	for p in _props:
		var row := HBoxContainer.new()
		var label := Label.new()
		label.text = p.prop
		label.custom_minimum_size.x = 130
		var slider := HSlider.new()
		slider.min_value = p.from
		slider.max_value = p.to
		slider.step = (p.to - p.from) / 200.0
		slider.value = p.obj.get(p.prop)
		slider.custom_minimum_size.x = 200
		var value := Label.new()
		value.text = "%.2f" % slider.value
		slider.value_changed.connect(func(v):
			p.obj.set(p.prop, v)
			value.text = "%.2f" % v
		)
		row.add_child(label)
		row.add_child(slider)
		row.add_child(value)
		$Panel/VBox.add_child(row)

# 角色的 _ready 里注册几行，就有了一整套滑块
func _ready() -> void:
	if OS.is_debug_build():
		DebugPanel.watch(self, "jump_speed", 100.0, 600.0)
		DebugPanel.watch(self, "gravity", 400.0, 3000.0)
		DebugPanel.watch(self, "fall_mult", 1.0, 3.0)
		DebugPanel.watch(self, "coyote_time", 0.0, 0.3)

func dump() -> void:
	var out := ""
	for p in _props:
		out += "%s = %.3f\n" % [p.prop, p.obj.get(p.prop)]
	print(out)
	DisplayServer.clipboard_set(out)     # 直接进剪贴板

什么不该数据驱动

这一章讲了很多「抠出来」的好处，但要有个边界，否则会走向另一个极端。

一个更根本的边界

数据驱动的对象应该是数值和组合，不是行为。

• ✓ 「这个敌人有 20 血、移速 40、每 1.2 秒攻击一次」→ 数据
• ✓ 「这个敌人挂了 飞行 + 射击 + 护甲 三个组件」→ 数据（第 19 章的组合）
• ✗ 「这个敌人在血量低于 30% 且玩家在左边时，先后退再放技能」→ 代码

本章小结

• 迭代速度是一个设计指标，不只是工程整洁度 —— 迭代贵的时候，人会不自觉降低标准。
• 法则：任何你会调超过 20 次的东西，都值得为它做更快的调整方式。
• 三个层次：@export（十分钟，覆盖 80%）→ Resource（多套配置切换）→ 外部文件热重载。
• 被低估的一招：Godot 编辑器的「远程」标签页能改运行中场景的属性，几乎等于免费的热重载。
• Resource 化的意外收益：配置切换本身就变成了玩法（冰面、水下、变身）。
• 热重载必须有两条防线：解析失败保留旧配置、缺键返回默认值。会崩的热重载等于没有。
• 调参面板别忘了「导出当前值」按钮。
• 边界：数据驱动数值和组合，不要数据驱动行为。逻辑写在代码里。