goose-adventure-game

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

鹅骑鹅冒险游戏引擎

Nils Goose Adventure Game Engine

概述

Overview

这是一个完整的文字冒险游戏引擎，专为《尼尔斯骑鹅旅行记》故事设计。游戏引擎支持：

剧情节点系统 - 分支叙事，多个结局
状态管理 - 生命值、道德值、大小值、知识值
存档系统 - 多槽位存档，自动保存
成就系统 - 追踪玩家成就
物品栏管理 - 收集和使用物品
条件触发 - 基于状态的选项解锁

This is a complete text adventure game engine designed specifically for the story The Wonderful Adventures of Nils. The game engine supports:

Plot Node System - Branching narrative with multiple endings
State Management - Health points, morality, size value, knowledge value
Save System - Multi-slot saving with auto-save
Achievement System - Tracks player achievements
Inventory Management - Collect and use items
Conditional Trigger - Unlock options based on state

快速开始

Quick Start

1. 运行游戏

1. Run the Game

bash

undefined

bash

undefined

使用 Python 运行游戏引擎

Run the game engine with Python

python3 scripts/game_engine.py

或使用 pnpm（如果需要）

Or use pnpm (if needed)

pnpm run game

undefined

pnpm run game

undefined

2. 游戏文件结构

2. Game File Structure

goose-adventure-game/
├── scripts/
│   ├── game_engine.py      # 游戏引擎主类
│   ├── game_script.json    # 游戏剧本数据
│   └── save_manager.py     # 存档管理器
├── saves/                  # 存档目录（自动创建）
└── SKILL.md               # 本文档

goose-adventure-game/
├── scripts/
│   ├── game_engine.py      # Main game engine class
│   ├── game_script.json    # Game script data
│   └── save_manager.py     # Save manager
├── saves/                  # Save directory (auto-created)
└── SKILL.md               # This document

3. 基本使用

3. Basic Usage

python

from scripts.game_engine import GameEngine, load_script_from_file

python

from scripts.game_engine import GameEngine, load_script_from_file

加载游戏脚本

Load game script

script = load_script_from_file("scripts/game_script.json")

创建游戏引擎

Create game engine

engine = GameEngine(script, save_dir="./saves")

渲染当前场景

Render current scene

scene = engine.render_scene() print(f"{scene['title']}\n{scene['description']}")

显示选项

Display choices

for choice in scene['choices']: print(f"{choice['index']}: {choice['text']}")

玩家做出选择

Player makes a choice

engine.make_choice(0) # 选择第一个选项

engine.make_choice(0) # Choose the first option

保存游戏

Save game

engine.save_game("slot1")

undefined

engine.save_game("slot1")

undefined

核心功能

Core Features

1. 游戏状态系统

1. Game State System

游戏状态包含以下属性：

属性	类型	范围	说明
`hp`	int	0-100	生命值
`morality`	int	0-100	道德值（决定结局）
`size`	int	0-100	大小值（0=拇指大小，100=正常）
`knowledge`	int	0-1000	知识值
`inventory`	list	-	物品栏
`achievements`	list	-	成就列表
`flags`	dict	-	事件标志

The game state includes the following attributes:

Attribute	Type	Range	Description
`hp`	int	0-100	Health points
`morality`	int	0-100	Morality value (determines ending)
`size`	int	0-100	Size value (0=thumb-sized, 100=normal)
`knowledge`	int	0-1000	Knowledge value
`inventory`	list	-	Inventory
`achievements`	list	-	Achievement list
`flags`	dict	-	Event flags

2. 场景系统

2. Scene System

每个场景包含：

json

{
  "id": "scene_id",
  "title": "场景标题",
  "description": "场景描述",
  "choices": [
    {
      "text": "选项文本",
      "next_scene": "下一场景ID",
      "requirements": {
        "morality_min": 50,
        "has_item": "key"
      },
      "effects": {
        "moral_change": 10,
        "add_item": "key",
        "set_flag": {"met_npc": true}
      }
    }
  ]
}

Each scene includes:

json

{
  "id": "scene_id",
  "title": "Scene Title",
  "description": "Scene Description",
  "choices": [
    {
      "text": "Option Text",
      "next_scene": "Next Scene ID",
      "requirements": {
        "morality_min": 50,
        "has_item": "key"
      },
      "effects": {
        "moral_change": 10,
        "add_item": "key",
        "set_flag": {"met_npc": true}
      }
    }
  ]
}

3. 条件触发系统

3. Conditional Trigger System

支持的触发条件：

```
has_item
```
- 检查物品
```
flag
```
- 检查事件标志
```
morality_min/max
```
- 道德值范围
```
size_min/max
```
- 大小值范围
```
has_achievement
```
- 检查成就

Supported trigger conditions:

```
has_item
```
- Check for items
```
flag
```
- Check event flags
```
morality_min/max
```
- Morality value range
```
size_min/max
```
- Size value range
```
has_achievement
```
- Check for achievements

4. 效果系统

4. Effect System

支持的效果类型：

```
add_item
```
/
```
remove_item
```
- 物品管理
```
hp_change
```
- 生命值变化
```
size_change
```
- 大小值变化
```
set_flag
```
- 设置事件标志
```
add_achievement
```
- 添加成就
```
moral_change
```
- 道德值变化
```
knowledge_gain
```
- 获得知识

Supported effect types:

```
add_item
```
/
```
remove_item
```
- Inventory management
```
hp_change
```
- Health points change
```
size_change
```
- Size value change
```
set_flag
```
- Set event flags
```
add_achievement
```
- Add achievements
```
moral_change
```
- Morality value change
```
knowledge_gain
```
- Gain knowledge

存档系统

Save System

使用存档管理器

Use Save Manager

python

from scripts.save_manager import SaveManager

manager = SaveManager(save_dir="./saves")

python

from scripts.save_manager import SaveManager

manager = SaveManager(save_dir="./saves")

保存游戏

Save game

manager.save_game("slot1", game_data)

加载游戏

Load game

game_data = manager.load_game("slot1")

列出所有存档

List all saves

saves = manager.list_saves()

删除存档

Delete save

manager.delete_save("slot1")

undefined

manager.delete_save("slot1")

undefined

自动保存

Auto-Save

python

from scripts.save_manager import AutoSaveManager

auto_save = AutoSaveManager(manager, auto_save_interval=5)

python

from scripts.save_manager import AutoSaveManager

auto_save = AutoSaveManager(manager, auto_save_interval=5)

每个场景变化后检查

Check after each scene change

auto_save.on_scene_change("autosave", game_data)

强制保存

Force save

auto_save.force_save("quicksave", game_data)

undefined

auto_save.force_save("quicksave", game_data)

undefined

游戏剧本编辑

Game Script Editing

添加新场景

Add New Scene

在

game_script.json

的

scenes

数组中添加：

json

{
  "id": "my_new_scene",
  "chapter": 1,
  "title": "新场景标题",
  "description": "场景描述...",
  "choices": [
    {
      "text": "选项1",
      "next_scene": "scene_a"
    },
    {
      "text": "选项2",
      "next_scene": "scene_b",
      "requirements": {"morality_min": 50},
      "effects": {"moral_change": 10}
    }
  ]
}

Add to the

scenes

array in

game_script.json

json

{
  "id": "my_new_scene",
  "chapter": 1,
  "title": "New Scene Title",
  "description": "Scene description...",
  "choices": [
    {
      "text": "Option 1",
      "next_scene": "scene_a"
    },
    {
      "text": "Option 2",
      "next_scene": "scene_b",
      "requirements": {"morality_min": 50},
      "effects": {"moral_change": 10}
    }
  ]
}

添加新结局

Add New Ending

在

game_script.json

的

endings

数组中添加：

json

{
  "id": "special_ending",
  "title": "特殊结局",
  "description": "结局描述...",
  "requirements": {
    "morality_min": 80,
    "flag": ["special_event", true]
  }
}

Add to the

endings

array in

game_script.json

json

{
  "id": "special_ending",
  "title": "Special Ending",
  "description": "Ending description...",
  "requirements": {
    "morality_min": 80,
    "flag": ["special_event", true]
  }
}

成就系统

Achievement System

预定义成就

Predefined Achievements

游戏包含以下成就：

🥚 初章：变小的人 - 完成第一章
🕊️ 翅膀的守护者 - 救下莫顿
🦊 狐狸的死敌 - 帮助雁群对抗狐狸
🌍 自然观察者 - 知识值达到100
📚 小小博物学家 - 知识值达到300
🗺️ 地理大师 - 知识值达到500
⭐ 智慧之星 - 知识值达到800
💖 善良之心 - 道德值达到80
🦸‍♂️ 真正的勇者 - 达成完美结局

The game includes the following achievements:

🥚 Prologue: The Shrunk One - Complete Chapter 1
🕊️ Guardian of Wings - Save Morten
🦊 Enemy of the Fox - Help the geese fight the fox
🌍 Nature Observer - Reach 100 knowledge points
📚 Little Naturalist - Reach 300 knowledge points
🗺️ Geography Master - Reach 500 knowledge points
⭐ Star of Wisdom - Reach 800 knowledge points
💖 Kind Heart - Reach 80 morality
🦸‍♂️ True Hero - Unlock the perfect ending

添加自定义成就

Add Custom Achievement

在场景的效果中添加：

json

{
  "effects": {
    "add_achievement": "🏆 自定义成就"
  }
}

Add to the scene's effects:

json

{
  "effects": {
    "add_achievement": "🏆 Custom Achievement"
  }
}

游戏调试

Game Debugging

查看当前状态

View Current State

python

state = engine.state
print(f"生命值: {state.hp}")
print(f"道德值: {state.morality}")
print(f"知识值: {state.knowledge}")
print(f"物品: {state.inventory}")
print(f"成就: {state.achievements}")

python

state = engine.state
print(f"Health: {state.hp}")
print(f"Morality: {state.morality}")
print(f"Knowledge: {state.knowledge}")
print(f"Items: {state.inventory}")
print(f"Achievements: {state.achievements}")

跳转到指定场景

Jump to Specified Scene

python

engine.state.current_scene = "target_scene_id"

python

engine.state.current_scene = "target_scene_id"

设置状态值

Set State Values

python

engine.state.morality = 80
engine.state.knowledge = 500
engine.state.inventory.append("special_item")

python

engine.state.morality = 80
engine.state.knowledge = 500
engine.state.inventory.append("special_item")

扩展游戏

Extend the Game

创建自定义故事

Create Custom Story

复制
```
game_script.json
```
作为模板
修改
```
game_info
```
中的标题和描述
编辑或替换
```
scenes
```
数组中的场景
更新
```
endings
```
数组中的结局

Copy
```
game_script.json
```
as a template
Modify the title and description in
```
game_info
```
Edit or replace scenes in the
```
scenes
```
array
Update endings in the
```
endings
```
array

添加新功能

Add New Features

游戏引擎采用模块化设计，可以轻松扩展：

在
```
GameEngine
```
类中添加新方法
在
```
GameState
```
类中添加新属性
创建新的效果类型

The game engine uses a modular design and can be easily extended:

Add new methods to the
```
GameEngine
```
class
Add new attributes to the
```
GameState
```
class
Create new effect types

最佳实践

Best Practices

游戏设计

Game Design

道德选择 - 提供有意义的选择，让玩家思考
循序渐进 - 从简单开始，逐步增加复杂性
反馈清晰 - 让玩家了解选择的后果
多结局 - 根据玩家选择提供不同结局

Moral Choices - Provide meaningful choices that make players think
Progressive Complexity - Start simple and gradually increase complexity
Clear Feedback - Let players understand the consequences of their choices
Multiple Endings - Offer different endings based on player choices

剧情编写

Plot Writing

描述生动 - 使用感官语言描述场景
选项明确 - 每个选项应该清晰表达后果
逻辑一致 - 确保剧情逻辑连贯
知识融入 - 在剧情中自然地融入知识

Vivid Descriptions - Use sensory language to describe scenes
Clear Options - Each option should clearly express consequences
Logical Consistency - Ensure the plot is logically coherent
Knowledge Integration - Naturally integrate knowledge into the plot

技术实现

Technical Implementation

数据驱动 - 将故事数据与引擎代码分离
可测试性 - 确保每个功能都可以独立测试
错误处理 - 优雅处理加载失败等情况
性能优化 - 避免重复加载资源

Data-Driven - Separate story data from engine code
Testability - Ensure each feature can be tested independently
Error Handling - Gracefully handle situations like loading failures
Performance Optimization - Avoid repeated resource loading