hello-agents/code/chapter15/Helloagents-AI-Town/helloagents-ai-town/scripts

🎮 赛博小镇 - GDScript脚本说明

📁 脚本文件列表

scripts/
├── config.gd          # 全局配置
├── api_client.gd      # API通信客户端
├── player.gd          # 玩家控制
├── npc.gd            # NPC行为
├── dialogue_ui.gd    # 对话UI
└── main.gd           # 主场景逻辑

---

📄 脚本详解

1. config.gd (全局配置)

用途: 存储全局常量和配置

关键配置:

const API_BASE_URL = "http://localhost:8000"  # 后端API地址
const PLAYER_SPEED = 200.0                     # 玩家速度
const NPC_STATUS_UPDATE_INTERVAL = 30.0        # NPC更新间隔

使用方法:

# 在任何脚本中访问
Config.log_info("消息")
var speed = Config.PLAYER_SPEED

---

2. api_client.gd (API客户端)

用途: 与FastAPI后端通信

主要方法:

• send_chat(npc_name, message) - 发送对话
• get_npc_status() - 获取NPC状态
• get_npc_list() - 获取NPC列表

信号:

• chat_response_received(npc_name, message) - 收到对话回复
• chat_error(error_message) - 对话错误
• npc_status_received(dialogues) - 收到NPC状态

使用示例:

# 获取API客户端
var api = get_node("/root/APIClient")

# 发送对话
api.send_chat("张三", "你好")

# 监听回复
api.chat_response_received.connect(_on_response)

func _on_response(npc_name, message):
    print(npc_name + ": " + message)

---

3. player.gd (玩家控制)

用途: 处理玩家移动和交互

关键功能:

• WASD/方向键移动
• E键与NPC交互
• 检测附近的NPC

节点要求:

Player (CharacterBody2D)
├── Sprite2D
├── CollisionShape2D
└── Camera2D

自定义参数:

@export var speed: float = 200.0  # 在Inspector中可调整

---

4. npc.gd (NPC行为)

用途: NPC交互和状态显示

关键功能:

• 检测玩家进入/离开交互范围
• 显示NPC名字和对话
• 更新NPC状态

节点要求:

NPC (Node2D)
├── Sprite2D
├── InteractionArea (Area2D)
│   └── CollisionShape2D
├── NameLabel (Label)
└── DialogueLabel (Label)

导出参数:

@export var npc_name: String = "张三"
@export var npc_title: String = "Python工程师"

使用方法:

1. 在Inspector中设置NPC名字和职位
2. 脚本会自动处理交互逻辑

---

5. dialogue_ui.gd (对话UI)

用途: 对话界面管理

关键功能:

• 显示/隐藏对话框
• 处理玩家输入
• 显示对话历史
• 与API通信

节点要求:

DialogueUI (CanvasLayer)
└── Panel
    ├── NPCName (Label)
    ├── NPCTitle (Label)
    ├── DialogueText (RichTextLabel)
    ├── PlayerInput (LineEdit)
    ├── SendButton (Button)
    └── CloseButton (Button)

使用方法:

# 开始对话
get_tree().call_group("dialogue_system", "start_dialogue", "张三")

---

6. main.gd (主场景)

用途: 管理整个游戏场景

关键功能:

• 定时更新NPC状态
• 分发NPC对话到各个NPC节点
• 协调各个系统

节点要求:

Main (Node2D)
├── TileMapLayer (地图)
├── Player (实例化)
├── NPCs (Node2D)
│   ├── NPC_Zhang (实例化)
│   ├── NPC_Li (实例化)
│   └── NPC_Wang (实例化)
└── DialogueUI (实例化)

---

🔧 如何使用这些脚本

步骤1: 设置AutoLoad

在 Project -> Project Settings -> AutoLoad 中添加:

• config.gd -> 名称: Config
• api_client.gd -> 名称: APIClient

步骤2: 附加脚本到场景

• player.tscn -> 附加 player.gd
• npc.tscn -> 附加 npc.gd
• dialogue_ui.tscn -> 附加 dialogue_ui.gd
• main.tscn -> 附加 main.gd

步骤3: 配置节点

确保每个场景的节点结构与脚本要求一致。

步骤4: 设置参数

在Inspector中设置导出参数(如NPC名字、速度等)。

---

🐛 调试技巧

查看日志

所有脚本都使用 Config.log_info() 输出日志,在Godot的 Output 面板查看。

常见日志:

[INFO] API客户端初始化完成
[INFO] 玩家初始化完成
[INFO] NPC初始化: 张三
[INFO] 进入NPC范围: 张三
[API] POST /chat -> {"npc_name":"张三","message":"你好"}
[INFO] 收到NPC回复: 张三 -> 你好!我是Python工程师...

启用调试模式

在 config.gd 中:

const DEBUG_MODE = true  # 显示详细日志
const SHOW_INTERACTION_RANGE = true  # 显示交互范围

---

📊 信号流程图

玩家按E键
    ↓
player.gd: interact_with_npc()
    ↓
发送信号到 dialogue_system 组
    ↓
dialogue_ui.gd: start_dialogue(npc_name)
    ↓
显示对话框,玩家输入消息
    ↓
dialogue_ui.gd: send_message()
    ↓
api_client.gd: send_chat(npc_name, message)
    ↓
HTTP请求到FastAPI后端
    ↓
api_client.gd: _on_chat_request_completed()
    ↓
发出信号: chat_response_received
    ↓
dialogue_ui.gd: _on_chat_response_received()
    ↓
显示NPC回复

---

🎯 扩展建议

添加新NPC

1. 在 main.tscn 中实例化 npc.tscn
2. 设置NPC名字和位置
3. 在 main.gd 的 get_npc_node() 中添加映射

添加新功能

1. 在 config.gd 中添加配置
2. 在 api_client.gd 中添加新API方法
3. 在相应脚本中实现逻辑

优化性能

1. 减少 NPC_STATUS_UPDATE_INTERVAL 的更新频率
2. 使用对象池管理UI元素
3. 优化TileMap的碰撞层

---

📚 参考资源

• Godot文档: https://docs.godotengine.org/
• GDScript教程: https://gdscript.com/
• FastAPI文档: https://fastapi.tiangolo.com/

---

❓ 常见问题

Q: 如何修改API地址? A: 编辑 config.gd 中的 API_BASE_URL

Q: 如何添加更多NPC? A: 实例化 npc.tscn,设置参数,在 main.gd 中添加引用

Q: 如何自定义对话框样式? A: 编辑 dialogue_ui.tscn,修改Panel和Label的主题

Q: 如何禁用调试日志? A: 在 config.gd 中设置 DEBUG_MODE = false