Player Doll

A feature-rich player doll mod that supports creating and placing custom player doll entities. The mod provides default Steve and Alex dolls, and supports dynamically loading custom skin texture dolls from the game directory. Additionally, the mod features a powerful pose and action system, allowing you to set various static poses and dynamic animations for your dolls.

✨ Features

Core Features

• Default Dolls: Provides Steve (wide arms) and Alex (slim arms) default dolls
• Dynamic Loading: Automatically scans and registers custom skin texture dolls from the game directory
• Right-click Placement: Use doll items to right-click blocks and place corresponding doll entities
• Pose System: Supports custom static pose configurations (standing, sitting, lying, etc.)
• Action System: Supports creating dynamic animation sequences (waving, dancing, etc.) with loop playback and keyframe interpolation
• Model Types: Supports both wide-armed (Steve) and slim-armed (Alex) model types

📋 Requirements

• Minecraft Version: 1.21.1
• NeoForge Version: 21.1.217 or higher
• Java Version: 21 or higher

Installation Steps

1. Ensure NeoForge 21.1.217 or higher is installed
2. Place the mod file (.jar) into the mods folder
3. Launch the game, the mod will automatically create necessary configuration directories

---

🎮 Player Guide

Basic Usage

1. Enter creative mode and open the inventory
2. Find doll items in the "Player Doll" tab
3. Hold a doll item and right-click a block to place the corresponding doll entity next to it

Adding Custom Skin Dolls

The mod supports automatically loading custom skin textures from the game directory, allowing you to add new dolls without modifying code.

📁 Directory Location

Custom skin files should be placed in the following directory:

Game Root Directory/
└── player_doll/
    └── png/              # Custom skin texture directory (auto-created on first launch)
        ├── SMy_Character.png
        └── A123_ABC__qwe.png

📝 File Naming Rules

• File names must start with S or A, indicating the model type:
  • S = Wide-armed model (Steve model)
  • A = Slim-armed model (Alex model)
• The part after the first character will be used as the doll's display name
• Name processing rules:
  • Single underscore _ will be replaced with a space
  • Double underscore __ will be replaced with a single underscore _

📊 Naming Examples

File Name	Model Type	Display Name	Notes
SMy_Character.png	Wide-armed	My Character	Single underscore becomes space
A123_ABC__qwe.png	Slim-armed	123 ABC_qwe	Single underscore becomes space, double underscore becomes single
SHero_Doll.png	Wide-armed	Hero Doll	Single underscore becomes space
AVillager_Guard.png	Slim-armed	Villager Guard	Single underscore becomes space

🔄 Usage Workflow

1. Place skin texture PNG files into the player_doll/png/ directory
2. Launch the game or press F3+T to reload resource packs
3. The mod will automatically scan the directory and register all PNG files that match the rules
4. Find newly registered doll items in the "Player Doll" tab in creative mode inventory
5. Use doll items to place corresponding doll entities

⚠️ Important Notes

• The first character of the file name must be S or A, otherwise the file will be ignored
• File name must be at least 2 characters long (first character + at least 1 character)
• Only PNG format image files are supported
• Skin texture files should follow Minecraft standard skin format (64x64 or 64x32 pixels)
• Files that don't match the rules will be skipped and a warning will be logged
• The directory is automatically scanned when the mod starts

Configuring Doll Poses and Actions

The mod supports customizing doll poses and actions through JSON configuration files. Configuration files are located in the player_doll/ directory.

📂 Configuration File Directory Structure

Game Root Directory/
└── player_doll/
    ├── png/              # Custom skin texture directory
    ├── poses/            # Pose configuration file directory
    │   ├── standing.json
    │   ├── sitting.json
    │   └── ...
    ├── actions/          # Action configuration file directory
    │   ├── wave.json
    │   ├── dance.json
    │   └── ...
    └── README.md         # Detailed configuration documentation

For detailed configuration instructions, please refer to the player_doll/README.md file, which includes:

• Pose file format and field descriptions
• Action file format and keyframe configuration
• Angle reference values and common pose examples
• Complete usage tutorials and examples

🔄 Reloading Configuration

After modifying configuration files, press F3+T to reload resource packs to apply changes without restarting the game.

Configuration Options

Mod configuration file is located at config/player_doll_addon-common.toml:

• testMode (Test Mode):
  • Type: Boolean
  • Default: true
  • Description: When enabled, outputs detailed debug logs to help analyze skin loading and model recognition issues

---

🐛 FAQ

Q: Custom skin not displaying?

A: Please check:

1. Whether the file name starts with S or A
2. Whether the file is a valid PNG format
3. Whether the file is placed in the player_doll/png/ directory
4. Whether you pressed F3+T to reload resource packs
5. Check log files for error messages

Q: How to modify doll poses?

A: Edit JSON files in the player_doll/poses/ directory, or create new pose files. For detailed instructions, please refer to player_doll/README.md.

Q: How to create custom actions?

A: Create JSON files in the player_doll/actions/ directory and define keyframe sequences. For detailed instructions, please refer to player_doll/README.md.

Q: What to do if the mod crashes?

A:

1. Check if Minecraft, NeoForge, and Java versions match
2. Check error logs in the logs/ directory
3. Enable test mode (testMode = true) to view detailed logs
4. Check if configuration file formats are correct

---

📄 License

This project is licensed under the MIT License.

The MIT License is a permissive open-source license that allows:

• ✅ Commercial use
• ✅ Modification
• ✅ Distribution
• ✅ Private use

The only requirement is to retain the copyright notice and license text.

For the complete license text, please see the LICENSE file.

---

👤 Author

Author: 蓝也（lan_ye）

---

🇨🇳 中文说明

简介

Player Doll 是一个功能丰富的玩家玩偶模组，支持创建和放置自定义玩家玩偶实体。模组提供了 Steve 和 Alex 的默认玩偶，并支持从游戏目录动态加载自定义皮肤材质玩偶。此外，模组还提供了强大的姿态（Poses）和动作（Actions）系统，让您可以为玩偶设置各种静态姿势和动态动画。

核心功能

• 默认玩偶：提供 Steve（粗手臂）和 Alex（细手臂）的默认玩偶
• 动态加载：从游戏目录自动扫描并注册自定义皮肤材质玩偶
• 右键放置：使用玩偶物品右键方块可以在指定位置放置玩偶实体
• 姿态系统：支持自定义静态姿势配置（如站立、坐下、趴下等）
• 动作系统：支持创建动态动画序列（如挥手、跳舞等），支持循环播放和关键帧插值
• 模型类型：支持粗手臂（Steve）和细手臂（Alex）两种模型类型

快速使用

1. 安装要求：Minecraft 1.21.1，NeoForge 21.1.217+，Java 21+
2. 基础使用：创造模式 → 物品栏"玩家玩偶"标签 → 右键方块放置
3. 自定义皮肤：将 PNG 文件放入 player_doll/png/ 目录，文件名以 S（粗手臂）或 A（细手臂）开头，按 F3+T 重载
4. 配置姿态和动作：在 player_doll/poses/ 和 player_doll/actions/ 目录下创建 JSON 配置文件，详细说明请查看 player_doll/README.md

常见问题

• 皮肤不显示：检查文件名是否以 S/A 开头、格式是否正确、是否重载资源包
• 修改姿势：编辑 player_doll/poses/ 目录下的 JSON 文件
• 创建动作：在 player_doll/actions/ 目录下创建 JSON 文件定义关键帧
• 模组崩溃：检查版本匹配、查看错误日志、启用测试模式

许可证

本项目采用 MIT License 开源许可证，允许商业使用、修改、分发和私人使用。

---

Last updated: 2025-01-XX