ppg-modkit/AGENTS.md

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:

{
  "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:

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