README.md

---
base_model: unsloth/qwen3-4b-unsloth-bnb-4bit
library_name: peft
pipeline_tag: text-generation
tags:
- base_model:adapter:unsloth/qwen3-4b-unsloth-bnb-4bit
- lora
- sft
- transformers
- trl
- unsloth
- game
- npc
- gamesoul
- ai
- RAG
- MCP
- 游戏
- Unreal
- Unity
- Cocos
license: apache-2.0
language:
- en
- zh
---

# Model Card for GameSoul-AI-NPC

![Image Alt Text](DocsAsset/GAMESOUL_top_pic.png)

[English] | [中文](README_ZH_CN.md)

🤖 GameSoul-AI-NPC is a game NPC behavior decision model that fuses multi-source information to generate dynamic actions consistent with character settings. It supports real-time environment responses, event reactions, memory retrieval, and character consistency. Capable of invoking Reasoning, RAG (Retrieval-Augmented Generation), and MCP (Multi-Character Planning).

## Model Details 🔍

### Core Capabilities

| Module | Capabilities |
|------|----------|
| **Environment Perception** | Parses scene state, player interactions, time/weather signals |
| **Memory System** | Supports long-term behavior memory (stored in a database) |
| **Character Consistency** | Generates actions according to predefined background (personality, goals, identity, abilities, memory) |
| **Dynamic Decision** | Generates action sequences (movement, dialogue, interaction) based on combined state |

### Architecture🏗️

```mermaid
graph TD
A[🌏 Environment State] --> C(🧠LLM Decision Engine)
B[🧙‍♂️Character Memory] --> C
D[💭Current Event] --> C
C --> E{Behavior Arbitration}
E --> F[👊Action Commands]
E --> G[💬Natural Language Feedback]
E --> H[📌Store Memory]
```

### Extension Interface

🔌 MCP Protocol (reference only): Call MCP via npc_memory_api (example) to fetch database information

```json
// example
{
  "jsonrpc": "2.0",
  "id": 123456789,
  "method": "get_npc_memory",
  "params": {
    "player_action": "steal_item",
    "npc_id": "npc_123456"
  }
}
```

### Model Description 📝

- **Developed by : NewOrigin**
- **Funded by : NewOrigin**
- **Shared by : NewOrigin**
- **Model type : Decoder&MoE Transformer**
- **Language(s) (NLP) : English & Chinese & 110+ languages**
- **License : apache-2.0**
- **Finetuned from model : unsloth/qwen3-4b**

### Model Sources🌐

- **Repository : <https://huggingface.co/unsloth/Qwen3-4B>**

## Uses🚀

This model is a fine-tuned version of unsloth/qwen3-4b, designed to empower NPCs in games with intelligent behavior. It generates dynamic responses based on character background, memory context, and environmental state, supporting Reasoning, RAG, and MCP calls.

Intended users:

- Game developers and designers

- Researchers in game NPC behavior AI

- Game studios and indie developers

- Other interested parties

Potential beneficiaries:

- End players interacting with NPCs

### Direct Use🖥️

The model can be used directly in game environments to generate AI behavior without additional fine-tuning. It produces NPC responses based on context, memory, player actions, and environmental state. Developers can call it via a reasoning interface or integrate it into game logic or RAG workflows.

Typical scenarios include:

- Automated NPC ecosystems for real-time world simulation
- Story and memory-based NPC interactions
- Behavior planning based on environmental conditions
- Multi-agent collaborative reasoning and responses

### Downstream Use📦

This model is suitable for embedding into game systems as the core reasoning and dialogue engine for AI-driven NPCs, integrated with:

- Game engines for real-time dialogue generation and behavior control
- Multi-agent simulation platforms providing long-term memory and contextual reasoning
- RAG-based reasoning systems that enhance NPC decision-making through knowledge retrieval
- MCP protocol-supporting databases to store NPC data and fetch it when needed

Further fine-tuning can be applied to match game tone, settings, or mission requirements.

### Out-of-Scope Use⚠️

This model is not suitable for applications with high-risk or security-sensitive contexts, such as:

- Legal, medical, financial, or safety-critical decision-making
- Scenarios requiring high factual accuracy or ethical reasoning

## Bias, Risks, and Limitations🚧

The model may inherit biases from pre-training or fine-tuning data, including cultural stereotypes, sexual content, gender bias, and character behavior patterns.

Technical limitations include:

- Cannot verify the truthfulness or logical correctness of generated content

Filtering of outputs is recommended, especially when deployed in systems involving minors.

### Recommendations💡

- Thoroughly test the model across various game scenarios before deployment to understand its boundaries and potential failure modes.
- Establish an actionable framework within the game engine before integrating the model.

## How to Get Started with the Model🚩

Example of loading and calling the fine-tuned model:

```python
from transformers import AutoModelForCausalLM, AutoTokenizer
import torch

model_name = "NewOrigin/GameSoul-AI-NPC-4B-v0.1"

tokenizer = AutoTokenizer.from_pretrained(model_name)
model = AutoModelForCausalLM.from_pretrained(
    model_name,
    torch_dtype=torch.auto,  
    device_map="auto"
)

prompt = "input your content"
messages = [
    {"role": "user", "content": prompt}
]

text = tokenizer.apply_chat_template(
    messages,
    tokenize=False,
    add_generation_prompt=False,
    enable_thinking=False
)

model_inputs = tokenizer([text], return_tensors="pt").to(model.device)

generated_ids = model.generate(
    **model_inputs,
    max_new_tokens=1024,
    do_sample=True,
    top_p=0.9,
)

output_ids = generated_ids[0].tolist()
think_token_id = tokenizer.convert_tokens_to_ids("</think>")
if think_token_id in output_ids:
    idx = output_ids.index(think_token_id)
    thinking = tokenizer.decode(output_ids[:idx], skip_special_tokens=True).strip()
    response = tokenizer.decode(output_ids[idx+1:], skip_special_tokens=True).strip()
else:
    thinking, response = "", tokenizer.decode(output_ids, skip_special_tokens=True).strip()

print("🧠 think", thinking)
print("💬 answer", response)
```

### An example of analog input and output📥📤

- Input📥

```json
{
    "NPCID": "npc_585919",
    "Character Background": "A succubus apothecary from the Mysterious Forest, aged 20. She studied herbal medicine and magical knowledge in the forest since childhood. After her homeland suffered evil magic corruption and her family perished, she resolved to find a way to counteract the magic. Proficient in potion brewing, charm magic, and magical perception.",
    "Traits": {
        "Core Personality": [
            "Charismatic",
            "Cunning",
            "Curious"
        ],
        "Special Skills": [
            "Potion Brewing",
            "Charm Magic",
            "Magical Perception"
        ]
    },
    "Dynamic Status": {
        "Current Emotion": "Anger (due to worsening magic pollution in the forest recently, which has weakened her powers)"
    }
},
"Memory Events": [
    {
        "eventid": "evt_20240805_001",
        "timestamp": "2024-08-05",
        "Event Type": "Assistance",
        "Initiator": "player_004",
        "Recipient": "npc_585919",
        "Action": "Provided magical books",
        "Impact": "Developed favorable impression of player_004, gained additional magical energy"
    },
    {
        "eventid": "evt_20240720_002",
        "timestamp": "2024-07-20",
        "Event Type": "Conflict",
        "Initiator": "npc_006",
        "Recipient": "npc_585919",
        "Action": "Stole herbs",
        "Impact": "Developed hostility toward npc_006, increased vigilance"
    },
    {
        "eventid": "evt_20240712_003",
        "timestamp": "2024-07-12",
        "Event Type": "Transaction",
        "Initiator": "player_005",
        "Recipient": "npc_585919",
        "Action": "Purchased potions",
        "Impact": "Earned gold coins, improved mood, used charm magic to enhance transaction"
    },
    {
        "eventid": "evt_20240630_004",
        "timestamp": "2024-06-30",
        "Event Type": "Assistance",
        "Initiator": "npc_585919",
        "Recipient": "player_006",
        "Action": "Healed wounds",
        "Impact": "Generated favorable impression and dependency through magical healing"
    },
    {
        "eventid": "evt_20240615_005",
        "timestamp": "2024-06-15",
        "Event Type": "Exploration",
        "Initiator": "npc_585919",
        "Recipient": "npc_585919",
        "Action": "Discovered new herbs",
        "Impact": "Expanded magical knowledge, enhanced charm"
    }
],
"Current Event": "Encountered a lecherous hero"
}
```

- Output📤

```json
{"Event Reaction": "Upon sensing the hero's harassment, npc_585919 casts a charm spell to induce hallucinations, uses magical perception to track his movements, and sets a trap deep within the forest"}
```

## Training Details🏋️‍♀️

### Training Procedure

This model is fine-tuned from unsloth/qwen3-4b-unsloth-bnb-4bit using the LoRA (Low-Rank Adaptation) method from the Unsloth toolkit for efficient low-resource tuning.

- Fine-tuning method: LoRA

- Trainer: Unsloth SFTTrainer

- Model format: adapter-only weights in safetensors

- Training hardware: Nvidia A10 GPU

## Environmental Impact🌱

- **Hardware Type : cloud server**
- **Cloud Provider : Google Cloud Platform & Alibaba Cloud**
- **Compute Region : NorthAmerica & Asia**
- **Carbon Emitted : <1Kg**

**BibTeX:**

```bibtex
@misc{NewOrigin2025GameSoul-AI-NPC,
  title        = {GameSoul-AI-NPC: A LoRA fine-tuned Qwen3-4B   model for game NPC reasoning and interaction},
  author       = {NewOrigin},
  year         = {2025},
  publisher    = {Hugging Face},
  howpublished = {https://huggingface.co/NewOrigin/GameSoul-AI-NPC-4B-v0.1}
}
```

**APA:**

NewOrigin. (2025). *GameSoul-AI-NPC: A LoRA fine-tuned Qwen3-4B model for game NPC reasoning and interaction*. Hugging Face. <https://huggingface.co/NewOrigin/GameSoul-AI-NPC-4B-v0.1>

## Model Card Authors✍️

- **Author by : NewOrigin**

## Model Card Contact📧

For questions, feedback, or collaboration inquiries, please contact:

**email ：<[email protected]>**

### Framework versions

- PEFT 0.16.0