# Game-Animal World

**Repository Path**: nullshow/animal-world

## Basic Information

- **Project Name**: Game-Animal World
- **Description**: 一个动态平衡的草原生态世界，实现了FSM和Boids算法。
- **Primary Language**: C++
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-29
- **Last Updated**: 2025-11-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Cpp, Algorithm

## README

# 动物世界 | Animal World

> 本项目基于我在大学期间完成的一次项目作业，仅用于展示个人技术能力。请勿将本代码用于课程作业提交或其他学术用途。如需参考，请注明出处。

> This project is based on an assignment I completed during my university studies. It is intended solely to showcase my technical capabilities. Please do not use this code for course submissions or other academic purposes. If you wish to reference it, proper attribution is required.

---

## 项目概览 | Project Overview

**技术栈 | Tech Stack**：C++ + raylib

**项目亮点 | Project Highlights**：

* 使用有限状态机（FSM）管理动物行为逻辑，实现状态切换与响应机制

  Utilized a **Finite State Machine (FSM)** to manage animal behavior logic, enabling clear state transitions and responsive mechanisms

* 应用 Boids 算法模拟乌鸦的群体飞行行为，增强自然感与动态表现

  Applied the **Boids algorithm** to simulate flocking behavior of crows, enhancing realism and dynamic expression

* 构建了基础生态循环机制，支持草扩散、动物繁殖与资源消耗

  Built a foundational ecological cycle system supporting grass growth and spread, animal reproduction, and resource consumption

---

## 核心机制 | Core Mechanics

创建一个由草、羊和狼组成的小型生态系统模拟。世界由三类实体构成：**草 (Grass)、羊 (Sheep)、狼 (Wolves)**，其行为通过有限状态机 (FSM) 实现；乌鸦 (Crows) 使用Boids算法。每个实体的 **感知 (Sense)、决策 (Decide)、行动 (Act)** 逻辑需要彼此分离。

每个实体在每次更新时都会执行动作 (Act)，但感知与决策的频率较低。例如：

- 每一帧实体都会移动 (Act)
- 每隔 5 帧才进行一次环境信息采集与决策 (Sense + Decide)

Create a small simulation of an ecosystem consisting of **Grass, Sheep, and Wolves**. The world is composed of three entities with specific behaviors implemented as **Finite State Machines (FSM)**; **Crows** are introduced using swarm behavior. Each entity’s **Sense, Decide, and Act** logic must be separated.

An agent acts (moves) every update, but sensing and deciding occur at a lower frequency. For example:

- Every frame the agent performs an action (Act)
- Every 5 frames the agent gathers information and evaluates decisions (Sense + Decide)

### 草 | Grass

- **Sense**: 检测是否被羊或狼踩踏

  ​             Detect if trampled by sheep or wolve

- **Decide**: 根据当前状态选择生长或扩散

  ​               Choose to grow or spread based on state and sensing

- **Act**:

  - 生长：提升生命值至最大值，成熟后保持一段时间；若被踩踏或吃掉则生命值减少，降至零时变为泥土

    Grow: Increase health up to max; mature grass persists; trampled/eaten reduces health, at zero becomes dirt

  - 扩散：尝试在相邻空间生成新草

    Spread: Attempt to create new grass in adjacent space

### 羊 | Sheep

- 初始数量：10只，随机分布

  Initial count: 10, placed randomly

- 每只羊有生命值，并在图形界面显示位置与状态

  Each sheep has health, position, and state shown graphically

- **Sense**: 感知周围环境。

  ​			 Gather info from surroundings

- **Decide**: 根据内部属性与感知信息选择行为

  ​			   Choose action based on state and sensing

- **Act**:

  - **Evade**: 逃离附近的狼。

    ​			  Run away from wolves

  - **Eat**: 吃草，降低草生命值并提升自身生命值

    ​		Consume grass, gain health

  - **Breed**: 达到生命阈值时繁殖新羊，消耗自身生命值

    ​			  Reproduce when health threshold reached, lose health in process

  - **Find**: 饥饿时向草移动

    ​           Move toward grass when hungry

  - **Wander**: 无草可见时随机游走

    ​                 Randomly move if no grass visible

- 每个动作周期都会因衰老损失少量生命值，生命值 ≤ 0 时死亡

  Health decreases each tick due to aging; sheep die at ≤ 0 health

### 狼 | Wolves

- 图形界面显示位置与状态

  Position and state shown graphically

- **Sense**: 感知周围环境

  ​			 Gather info from surroundings

- **Decide**: 根据内部属性与感知信息选择行为

  ​			   Choose action based on state and sensing

- **Act**:

  - **Eat**: 吃羊，获得生命值

    ​		Consume sheep, gain health

  - **Breed**: 健康成熟时繁殖新狼，消耗自身生命值

    ​			  Reproduce when healthy, lose health in process

  - **Pursue**: 饥饿时追逐附近的羊

    ​				Move toward sheep when hungry

  - **Wander**: 无羊可见时随机游走

    ​				 Randomly move if no sheep visible

- 每个周期都会损失生命值，生命值 ≤ 0 时死亡

  Health decreases each tick; wolves die at ≤ 0 health

**Wolves (English)**

- Position and state shown graphically.
- **Sense**: Gather info from surroundings.
- **Decide**: Choose action based on state and sensing.
- **Act**:
  - **Eat**: Consume sheep, gain health.
  - **Breed**: Reproduce when healthy, lose health in process.
  - **Pursue**: Move toward sheep when hungry.
  - **Wander**: Randomly move if no sheep visible.
- Health decreases each tick; wolves die at ≤ 0 health.

### 乌鸦 | Crows

- 初始数量：20只，形成群体

  Initial count: 20, forming a flock

- 遵循群体飞行（Boids）规则：

  Follow swarm (Boids) rules:

  - 保持接近但避免过度靠近

    Stay close but not too close

  - 避开其他乌鸦，同时尝试与群体方向一致

    Steer away from others while aligning with group direction

---

## 快速开始 | Getting Started

### 中文说明：

1. 使用 Visual Studio 2022 打开项目解决方案文件（`.sln`）或新建空项目并导入源码  
2. 选择“Release”或“Debug”模式，点击“本地 Windows 调试器”运行项目  

### English Instructions:

1. Open the `.sln` solution file in Visual Studio 2022, or create a new project and import the source files  
2. Select "Release" or "Debug" mode and run the project using "Local Windows Debugger"