feat: add initial People Playground mod development kit

2026-01-06 06:35:51 +03:00
parent b89c805060
commit 10dbfd434c
1095 changed files with 40267 additions and 1 deletions
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -0,0 +1,133 @@
+# People Playground Mod Development Project
+
+## Project Overview
+
+This is a comprehensive mod development project for People Playground v1.27. The project serves as both a learning resource and development toolkit for creating mods in the People Playground game. It includes complete documentation, code snippets, example mods, and extracted wiki content to facilitate mod development.
+
+## Technology Stack
+
+- **Programming Language**: C# (.cs files)
+- **Game Engine**: Unity (UnityEngine namespace)
+- **API**: ModAPI (People Playground's modding API)
+- **Documentation Tools**: Python scripts for web scraping and content extraction
+- **Asset Formats**: PNG images for sprites and thumbnails
+
+## Project Structure
+
+### Core Directories
+
+- **`ppg-snippets/`** - Code snippet library containing reusable C# code examples for common modding tasks (https://github.com/mestiez/ppg-snippets)
+- **`extracted_wiki_content/`** - Complete documentation extracted from the official People Playground wiki (https://wiki.studiominus.nl/)
+- **`parsing_docs/`** - Python utilities for extracting and processing documentation from the wiki (used only for generating `extracted_wiki_content/`)
+- **`SledgeHammer/`** - Example mod implementation demonstrating basic mod structure
+
+### Key Files
+
+- **`How-To-Mod-In-People-Playground.md`** - Comprehensive tutorial for creating mods (sourced from Steam Community)
+- **`mod.json`** - Mod configuration file (JSON format) defining metadata, entry point, and assets
+- **`script.cs`** - Main mod script file containing the C# implementation
+
+## Mod Configuration (mod.json)
+
+The `mod.json` file serves as the mod manifest with the following structure:
+
+```json
+{
+  "Name": "Mod Name",
+  "Author": "Author Name",
+  "Description": "Mod description",
+  "ModVersion": "0.1",
+  "GameVersion": "1.27.5",
+  "ThumbnailPath": "thumb.png",
+  "EntryPoint": "Mod.Mod",
+  "Tags": ["Fun"],
+  "Scripts": ["script.cs"]
+}
+```
+
+- **EntryPoint**: Must follow namespace.class format (e.g., "Mod.Mod")
+- **Scripts**: Array of C# script files to load
+- **GameVersion**: Target People Playground version compatibility
+
+## Code Organization
+
+### Namespace Convention
+All mod code uses the `Mod` namespace:
+```csharp
+namespace Mod
+{
+    public class Mod
+    {
+        public static void Main()
+        {
+            // Mod initialization code
+        }
+    }
+}
+```
+
+### ModAPI Usage Patterns
+- **Item Registration**: Use `ModAPI.Register()` with `Modification()` objects
+- **Asset Loading**: Use `ModAPI.LoadSprite()` for textures
+- **Category/Item Discovery**: Use `ModAPI.FindCategory()` and `ModAPI.FindSpawnable()`
+
+## Development Workflow
+
+### Asset Requirements
+See `CUSTOM-SETTINGS.md` for detailed asset style guidelines and visual requirements.
+
+**Folder Structure:** Use `sprites/` and `sfx/` subfolders for organization:
+```
+mod_folder/
+├── sprites/item.png
+└── sfx/impact.wav
+```
+
+### Mod Installation Path
+```
+C:\Program Files (x86)\Steam\steamapps\common\People Playground\Mods
+```
+
+### Important Development Notes
+- Disable Steam Cloud for People Playground to prevent file recreation issues
+- File naming within mod folders affects load order (alphabetical)
+- All script files must use .cs extension (C#)
+- Only mod.json uses JSON format, all other logic in C#
+
+## Notes
+
+- The `parsing_docs/` folder is used exclusively for generating the `extracted_wiki_content/` documentation and should not be considered part of the main mod development project
+
+## Code Snippets Library
+
+The `ppg-snippets/` directory contains examples for:
+- Basic mod entry points
+- Adding simple items and weapons
+- Creating humans and entities
+- Spawning particle effects
+- Event handling and activation
+- Environment modification
+- Debug visualization
+- Texture assignment for multi-sprite objects
+
+## Documentation Sources
+
+- **Extracted Wiki Content**: Complete API documentation from official wiki
+- **Steam Community Tutorial**: Step-by-step mod creation guide
+- **Code Snippets**: Practical examples for common modding scenarios
+
+## Build and Test Process
+
+1. Create mod folder in People Playground Mods directory
+2. Develop mod.json configuration file
+3. Implement C# script logic
+4. Create and import sprite assets
+5. Test in-game via mod loading system
+6. Debug using in-game console and visual feedback
+
+## Security Considerations
+
+- Mods run with full file system access within game directory
+- Steam Cloud synchronization can restore deleted files
+- Asset paths are relative to mod directory
+- No sandboxing - mods can access Unity engine fully