werewolf

package module
v0.0.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 10, 2025 License: Apache-2.0 Imports: 6 Imported by: 0

README

🐺 Werewolf Game Engine

Go Version Test Coverage License

一个纯 Go 实现的狼人杀游戏引擎库。完全不依赖网络层，可以嵌入任何应用程序。

✨ 特性

  • 🎯 纯游戏逻辑库 - 不管理连接，只负责游戏规则
  • 📡 事件驱动架构 - 通过事件系统通知游戏进展
  • 🔧 高度模块化 - Engine、Phase、Role、Skill 独立设计
  • 🧪 完整测试覆盖 - 70%+ 代码覆盖率，所有核心功能已测试
  • 🚀 零外部依赖 - 仅使用 Go 标准库
  • 📦 易于集成 - 可嵌入 WebSocket、gRPC、本地游戏等

📦 安装

go get github.com/Zereker/werewolf

🚀 快速开始

1. 创建游戏引擎
package main

import (
    "github.com/Zereker/werewolf"
)

func main() {
    // 配置游戏角色
    config := werewolf.Config{
        Roles: []werewolf.RoleType{
            werewolf.RoleTypeWerewolf,  // 狼人
            werewolf.RoleTypeWerewolf,  // 狼人
            werewolf.RoleTypeSeer,      // 预言家
            werewolf.RoleTypeWitch,     // 女巫
            werewolf.RoleTypeGuard,     // 守卫
            werewolf.RoleTypeHunter,    // 猎人
            werewolf.RoleTypeVillager,  // 村民
            werewolf.RoleTypeVillager,  // 村民
        },
    }

    // 创建引擎
    engine := werewolf.NewEngine(config)
}
2. 订阅游戏事件
// 订阅游戏开始事件
engine.Subscribe(werewolf.EventGameStarted, func(e werewolf.Event) {
    fmt.Printf("游戏开始！阶段: %v, 回合: %v\n",
        e.Data["phase"], e.Data["round"])
})

// 订阅阶段变化事件
engine.Subscribe(werewolf.EventPhaseStarted, func(e werewolf.Event) {
    fmt.Printf("进入阶段: %v\n", e.Data["phase"])
})

// 订阅玩家死亡事件
engine.Subscribe(werewolf.EventPlayerDied, func(e werewolf.Event) {
    fmt.Printf("玩家 %v 死亡\n", e.Data["playerID"])
})
3. 添加玩家并开始游戏
// 添加玩家
engine.AddPlayer("player1")
engine.AddPlayer("player2")
// ... 添加更多玩家

// 开始游戏（自动分配角色）
engine.Start()
4. 执行游戏行动
// 推进阶段
engine.AdvancePhase(werewolf.PhaseNight)

// 玩家执行行动
engine.PerformAction("player1", werewolf.ActionKill, "player2", nil)
engine.PerformAction("player3", werewolf.ActionCheck, "player1", nil)

// 推进到白天
engine.AdvancePhase(werewolf.PhaseDay)

📚 核心概念

Engine (游戏引擎)

负责管理游戏状态、玩家信息、胜利条件判定。

engine := werewolf.NewEngine(config)
engine.AddPlayer("alice")
engine.Start()
state := engine.GetState()
winner := engine.CheckWinCondition()
Phase (游戏阶段)

实现具体的游戏规则逻辑（夜晚、白天、投票）。

import "github.com/Zereker/werewolf/phase"

// 夜晚阶段
nightPhase := phase.NewNightPhase()
nightPhase.Start(players, 1)
nightPhase.AddAction(phase.PhaseAction{
    PlayerID:   "werewolf1",
    ActionType: werewolf.ActionKill,
    TargetID:   "victim",
}, players)
result, _ := nightPhase.Process(players)

// 投票阶段
votePhase := phase.NewVotePhase()
votePhase.AddAction(phase.PhaseAction{
    PlayerID:   "player1",
    ActionType: werewolf.ActionVote,
    TargetID:   "player2",
}, players)
Role (角色系统)

定义角色的阵营、技能和优先级。

import "github.com/Zereker/werewolf/role"

// 创建角色
werewolfRole, _ := role.New(werewolf.RoleTypeWerewolf)

// 获取角色信息
camp := werewolfRole.GetCamp()                              // CampEvil
skills := werewolfRole.GetAvailableSkills(werewolf.PhaseNight)  // [Kill, ...]
priority := werewolfRole.GetPriority(werewolf.PhaseNight)       // 1
Skill (技能系统)

定义技能的属性（阶段、优先级、目标需求）。

import "github.com/Zereker/werewolf/skill"

factory := skill.NewFactory()

// 创建单个技能
killSkill, _ := factory.Create(werewolf.SkillTypeKill)

// 为角色创建技能集
skills := factory.CreateSkillsForRole(werewolf.RoleTypeWerewolf)

🎮 支持的角色

角色 阵营 技能
狼人 (Werewolf) 狼人阵营 夜晚杀人
预言家 (Seer) 好人阵营 夜晚查验身份
女巫 (Witch) 好人阵营 解药救人、毒药杀人
守卫 (Guard) 好人阵营 夜晚守护
猎人 (Hunter) 好人阵营 死亡时可以开枪
村民 (Villager) 好人阵营 无特殊技能

🔄 游戏流程

开始 (Start)
  ↓
夜晚 (Night) - 狼人杀人、预言家查验、女巫救人/毒人、守卫守护
  ↓
白天 (Day) - 玩家发言讨论
  ↓
投票 (Vote) - 所有玩家投票驱逐
  ↓
检查胜利条件
  ↓
继续下一回合或游戏结束

📖 完整示例

查看 examples/ 目录获取完整的使用示例：

运行示例：

# 简单示例
go run examples/simple/main.go

# 完整游戏流程示例
go run examples/phase/main.go

🧪 测试

# 运行所有测试
go test ./...

# 查看测试覆盖率
go test -cover ./...

# 生成覆盖率报告
go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out

📊 测试覆盖率

包 覆盖率
werewolf (主包) 82.4%
phase 74.9%
role 80.0%
skill 100% 🎉
总体 ~70%

🏗️ 项目结构

werewolf/
├── engine.go           # 游戏引擎核心
├── werewolf.go         # 核心类型定义
├── simple_eventbus.go  # 事件总线实现
├── phase/              # 游戏阶段系统
│   ├── phase.go
│   ├── night_phase.go
│   ├── day_phase.go
│   └── vote_phase.go
├── role/               # 角色系统
│   ├── role.go
│   ├── base_role.go
│   └── ...
├── skill/              # 技能系统
│   ├── skill.go
│   ├── factory.go
│   └── ...
└── examples/           # 示例程序
    ├── simple/
    └── phase/

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📄 许可证

本项目采用 MIT 许可证。详见 LICENSE 文件。

🔗 相关资源

Made with ❤️ by Zereker

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type ActionType 

type ActionType string

ActionType 玩家行动类型 

const (
	ActionKill      ActionType = "kill"
	ActionCheck     ActionType = "check"
	ActionProtect   ActionType = "protect"
	ActionPoison    ActionType = "poison"
	ActionAntidote  ActionType = "antidote"
	ActionShoot     ActionType = "shoot"
	ActionSpeak     ActionType = "speak"
	ActionVote      ActionType = "vote"
	ActionLastWords ActionType = "last_words"
)

type Camp 

type Camp int

Camp represents player's camp 

const (
	CampGood Camp = iota // Good camp
	CampEvil             // Bad camp
	CampNone
)

func (Camp) String 

func (c Camp) String() string

type Config 

type Config struct {
	Roles           []RoleType
	EnableLastWords bool
}

Config 游戏配置

type Engine 

type Engine struct {
	// contains filtered or unexported fields
}

Engine 简化的游戏引擎 核心原则： 1. 不管理连接，只管理游戏状态 2. 通过事件通知游戏进展 3. 接受方法调用来处理行动

func NewEngine 

func NewEngine(config Config) *Engine

NewEngine 创建新的游戏引擎

func (*Engine) AddPlayer 

func (e *Engine) AddPlayer(playerID string) error

AddPlayer 添加玩家（游戏开始前）

func (*Engine) AdvancePhase 

func (e *Engine) AdvancePhase(nextPhase PhaseType) error

AdvancePhase 推进到下一个阶段（测试用）

func (*Engine) CheckWinCondition 

func (e *Engine) CheckWinCondition() Camp

CheckWinCondition 检查胜利条件

func (*Engine) EndGame 

func (e *Engine) EndGame(winner Camp)

EndGame 结束游戏

func (*Engine) GetPlayerState 

func (e *Engine) GetPlayerState(playerID string) (PlayerState, error)

GetPlayerState 获取单个玩家状态

func (*Engine) GetState 

func (e *Engine) GetState() GameState

GetState 获取游戏状态快照

func (*Engine) KillPlayer 

func (e *Engine) KillPlayer(playerID string, reason string) error

KillPlayer 杀死玩家（测试用）

func (*Engine) PerformAction 

func (e *Engine) PerformAction(playerID string, actionType ActionType, targetID string, data map[string]interface{}) error

PerformAction 执行玩家行动

func (*Engine) Start 

func (e *Engine) Start() error

Start 开始游戏

func (*Engine) Subscribe 

func (e *Engine) Subscribe(eventType EventType, handler EventHandler) SubscriptionID

Subscribe 订阅游戏事件

func (*Engine) Unsubscribe 

func (e *Engine) Unsubscribe(id SubscriptionID)

Unsubscribe 取消订阅

type Event 

type Event struct {
	Type      EventType
	Timestamp time.Time
	Data      interface{}
}

Event 游戏事件（简化版）

type EventHandler 

type EventHandler func(event Event)

EventHandler 事件处理函数

type EventType 

type EventType = event.EventType

EventType alias for event.EventType 

const (
	// 游戏生命周期事件
	EventGameStarted  EventType = "game.started"
	EventGameEnded    EventType = "game.ended"
	EventPhaseStarted EventType = "phase.started"
	EventPhaseEnded   EventType = "phase.ended"
	EventRoundChanged EventType = "round.changed"

	// 玩家事件
	EventPlayerDied      EventType = "player.died"
	EventPlayerRevived   EventType = "player.revived"
	EventPlayerProtected EventType = "player.protected"

	// 行动事件
	EventActionExecuted EventType = "action.executed"
	EventSkillUsed      EventType = "skill.used"
	EventVoteResult     EventType = "vote.result"

	// 特殊事件
	EventHunterShot EventType = "hunter.shot"
	EventLastWords  EventType = "last.words"
)

游戏事件类型常量

type GameState 

type GameState struct {
	Phase        PhaseType
	Round        int
	Players      []PlayerState
	AlivePlayers []string
	Winner       Camp
	IsEnded      bool
}

GameState 游戏状态快照（只读）

type PhaseType 

type PhaseType string

PhaseType represents werewolf phase 

const (
	PhaseNight PhaseType = "night" // Night phase
	PhaseDay   PhaseType = "day"   // Day phase
	PhaseVote  PhaseType = "vote"  // Vote phase
	PhaseStart PhaseType = "start" // Game start phase
	PhaseEnd   PhaseType = "end"   // Game end phase
	PhaseNone  PhaseType = "none"
)

type PlayerState 

type PlayerState struct {
	ID          string
	Role        RoleType
	IsAlive     bool
	IsProtected bool
}

PlayerState 玩家状态（只读快照）

type Role 

type Role interface {
	// GetName returns role name
	GetName() RoleType
	// GetCamp returns role's camp
	GetCamp() Camp
	// GetAvailableSkills returns available skills in specific phase
	GetAvailableSkills(phase PhaseType) []Skill
	// GetPriority returns role's action priority in specific phase
	GetPriority(phase PhaseType) int
}

Role interface defines role behavior

type RoleType 

type RoleType string

RoleType represents role type 

const (
	RoleTypeWerewolf RoleType = "werewolf" // Werewolf
	RoleTypeSeer     RoleType = "seer"     // Seer
	RoleTypeWitch    RoleType = "witch"    // Witch
	RoleTypeHunter   RoleType = "hunter"   // Hunter
	RoleTypeVillager RoleType = "villager" // Villager
	RoleTypeGuard    RoleType = "guard"    // Guard
)

func (RoleType) String 

func (r RoleType) String() string

type Skill 

type Skill interface {
	// GetName 获取技能名称
	GetName() SkillType
	// GetPhase 获取技能使用阶段
	GetPhase() PhaseType
	// GetPriority 获取技能优先级
	GetPriority() int
	// CanUseMultipleTimes 技能是否可以多次使用
	CanUseMultipleTimes() bool
	// RequiresTarget 技能是否需要目标
	RequiresTarget() bool
}

Skill 技能接口

type SkillType 

type SkillType string

SkillType represents skill type 

const (
	SkillTypeKill     SkillType = "kill"     // Kill skill
	SkillTypeCheck    SkillType = "check"    // Check skill
	SkillTypeProtect  SkillType = "protect"  // Protect skill
	SkillTypeAntidote SkillType = "antidote" // Antidote skill
	SkillTypePoison   SkillType = "poison"   // Poison skill
	SkillTypeVote     SkillType = "vote"     // Vote skill
	SkillTypeSpeak    SkillType = "speak"    // Speak skill
	SkillTypeShoot    SkillType = "shoot"    // Hunter shoot skill
)

func (SkillType) String 

func (s SkillType) String() string

type SubscriptionID 

type SubscriptionID string

SubscriptionID 订阅ID

Source Files

View all Source files

Directories

Path Synopsis
examples
phase command
simple command

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.