> ## Documentation Index
> Fetch the complete documentation index at: https://docs.monolisk.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# CORP Documentation

> Unity-like ECS framework for Roblox with built-in networking

<Note>**Reading time:** \~15 minutes</Note>

**CORP** (Component-Oriented Replicated Programming) is a powerful game development framework for Roblox built with roblox-ts. It provides a Unity-like ECS architecture with GameObjects and Components, along with a built-in networking system inspired by Unity's Netcode for GameObjects.

## 🚀 Quick Start

Get up and running in minutes:

1. **Install Required Tools**

   * Install VS Code extensions:
     * [roblox-ts](https://marketplace.visualstudio.com/items?itemName=Roblox-TS.vscode-roblox-ts)
     * [Rojo](https://marketplace.visualstudio.com/items?itemName=evaera.vscode-rojo)
   * Download and install [Rojo Studio Plugin](https://github.com/rojo-rbx/rojo/releases) (Rojo.rbxm)

2. **Clone the CORP Template**
   ```bash theme={null}
   git clone https://github.com/MonoliskSoftware/CORP-TEMPLATE
   cd CORP-TEMPLATE
   git submodule update --init --recursive
   npm install
   ```

3. **Configure your game**

   Update `GAMEPACKS/MYGAME/metadata.ts`:

   ```typescript theme={null}
   const metadata: Gamepacks.Config.Metadata = {
       name: "MyGameName",  // Change this
       // ... rest of config
   };
   ```

   Update `GAMECONFIG/gameinfo.ts`:

   ```typescript theme={null}
   const gameinfo: Unreal.Gameinfo = {
       rootPack: "MyGameName",  // Must match metadata name
       authority: Unreal.Authority.SERVER
   };
   ```

4. **Create your first component**

   In `GAMEPACKS/MYGAME/src/`:

   ```typescript theme={null}
   import { Behavior } from "CORP/shared/componentization/behavior";

   export class HelloWorld extends Behavior {
       public onStart(): void {
           print("Hello, CORP!");
       }
       
       public willRemove(): void {}
       protected getSourceScript(): ModuleScript {
           return script as ModuleScript;
       }
   }
   ```

5. **Export your component**

   In `GAMEPACKS/MYGAME/exports/components.ts`:

   ```typescript theme={null}
   const components: Config.Components = {
       mappings: {
           "hello_world": HelloWorld
       }
   };
   ```

6. **Start Development**

   Terminal 1 - Start Rojo:

   ```bash theme={null}
   rojo serve default.project.json
   ```

   Terminal 2 - Watch TypeScript:

   ```bash theme={null}
   npx rbxtsc --watch
   ```

   Connect Roblox Studio to Rojo and press Play!

👉 **[Full Getting Started Guide →](./getting-started)** | **[Unreal System Guide →](./unreal-system)**

## 📚 Documentation

### Core Documentation

| Guide                                        | Description                                                    |
| -------------------------------------------- | -------------------------------------------------------------- |
| **[Getting Started](./getting-started)**     | Installation, setup, and your first component                  |
| **[Roblox Studio](./roblox-studio)**         | Essential Roblox concepts for CORP developers                  |
| **[Core Concepts](./core-concepts)**         | GameObjects, Components, Behaviors, and lifecycle              |
| **[Networking](./networking)**               | NetworkObjects, NetworkBehaviors, NetworkedVariables, and RPCs |
| **[Scene Management](./scene-management)**   | Creating, loading, and managing game scenes                    |
| **[Unreal System](./unreal-system)**         | Gamepacks, authority models, and modular game organization     |
| **[Macros](./macros)**                       | Instance transformation and procedural generation              |
| **[ScriptableObjects](./scriptableobjects)** | Data assets and configuration management                       |
| **[Decorators](./decorators)**               | Using @SerializeField, @RequiresComponent, @RPC, and more      |
| **[Advanced Topics](./advanced-topics)**     | Spawn management, observables, optimization, and patterns      |

### Reference & Examples

| Guide                                | Description                                               |
| ------------------------------------ | --------------------------------------------------------- |
| **[API Reference](./api-reference)** | Complete API documentation for all classes and methods    |
| **[Examples](./examples)**           | Practical examples and tutorials for common game features |

## ✨ Features

### 🎮 Unity-Style Architecture

Familiar GameObject and Component patterns for organized game development.

```typescript theme={null}
const player = new GameObject("Player");
player.addComponent(PlayerController);
player.addComponent(HealthSystem, { maxHealth: 100 });
```

### 🌐 Built-in Networking

Automatic replication with NetworkObjects and NetworkBehaviors.

```typescript theme={null}
@RequiresComponent(NetworkObject)
export class PlayerSync extends NetworkBehavior {
    public readonly position = new NetworkedVariable<Vector3>(Vector3.zero);
}
```

### 📡 Type-Safe RPCs

Remote Procedure Calls with flexible configuration.

```typescript theme={null}
@RPC.Method({
    endpoints: [RPC.Endpoint.CLIENT_TO_SERVER],
    accessPolicy: RPC.AccessPolicy.OWNER
})
public attack(targetId: string): void {
    // Server validates and processes
}
```

### 🔄 Automatic State Sync

NetworkedVariables, Lists, Maps, and Sets synchronize automatically.

```typescript theme={null}
public readonly health = new NetworkedVariable<number>(100);
public readonly inventory = new NetworkedList<string>();
public readonly scores = new NetworkedMap<string, number>();
```

### 🎬 Scene Management

Load and manage game scenes with serialization support.

```typescript theme={null}
const scene: SceneSerialization.SceneDescription = {
    children: [
        {
            name: "Player",
            components: [
                { path: ["src", "components", "PlayerController"], data: {} }
            ],
            children: []
        }
    ]
};
```

### 🎯 Component Lifecycle

Predictable initialization and cleanup with lifecycle hooks.

```typescript theme={null}
export class MyComponent extends Behavior {
    public willStart(): void { /* Pre-init */ }
    public onStart(): void { /* Initialize */ }
    public onPropertiesApplied(): void { /* React to config */ }
    public willRemove(): void { /* Cleanup */ }
}
```

## 🎓 Learning Path

### 🟢 Beginner

1. **[Getting Started](./getting-started)** - Step-by-step tutorial to create your first game
2. **[Core Concepts](./core-concepts)** - Understanding GameObjects and Components
3. **[Unreal System](./unreal-system)** - Understanding Gamepacks and project structure

### 🟡 Intermediate

4. **[Scene Management](./scene-management)** - Advanced scene loading and organization
5. **[Macros](./macros)** - Transform instances into GameObjects procedurally
6. **[ScriptableObjects](./scriptableobjects)** - Create reusable data assets
7. **[Decorators](./decorators)** - Use component decorators effectively
8. **[Examples](./examples)** - Build player controllers, health systems, and weapons

### 🔴 Advanced

9. **[Networking](./networking)** - Create multiplayer experiences
10. **[Advanced Topics](./advanced-topics)** - Master advanced patterns and optimization
11. **[API Reference](./api-reference)** - Complete API reference

## 📖 Common Use Cases

See **[Examples](./examples)** for complete tutorials on:

* **Simple Player Controller** - Character movement and input
* **Health System** - Networked health with damage and respawn
* **Weapon System** - Shooting mechanics with server validation
* **Enemy AI** - Pathfinding and target tracking
* **Inventory System** - Item management and UI
* **Game Manager** - Match flow and win conditions

## 🔑 Key Concepts

### GameObjects

Entities in your game world that contain Components.

```typescript theme={null}
const enemy = new GameObject("Enemy");
enemy.setParent(parentObject);
```

### Components

Define behavior and data for GameObjects.

```typescript theme={null}
export class MyComponent extends Component {
    public onStart(): void { /* Initialize */ }
    public willRemove(): void { /* Cleanup */ }
}
```

### Behaviors

Components with serialization support.

```typescript theme={null}
export class MyBehavior extends Behavior {
    @SerializeField
    public configValue: number = 10;
}
```

### NetworkObjects

Make GameObjects replicate across the network.

```typescript theme={null}
const netObj = player.addComponent(NetworkObject);
netObj.spawn(); // Server only
```

### NetworkBehaviors

Components that replicate their state.

```typescript theme={null}
@RequiresComponent(NetworkObject)
export class MyNetworkBehavior extends NetworkBehavior {
    public readonly syncedValue = new NetworkedVariable<number>(0);
}
```

## 🛠️ Architecture Overview

```
CORP Framework
├── Core
│   ├── GameObject - Entity container
│   ├── Component - Base behavior class
│   └── Behavior - Serializable component
│
├── Networking
│   ├── NetworkObject - Replication root
│   ├── NetworkBehavior - Networked component
│   ├── NetworkedVariable - Synced state
│   └── RPC - Remote procedure calls
│
├── Scene Management
│   ├── SceneManager - Scene lifecycle
│   ├── Scene - Scene container
│   └── SceneSerialization - Scene format
│
└── Utilities
    ├── Signal - Event system
    ├── Collector - Resource cleanup
    └── Identification - ID generation
```

## 🎯 Best Practices

### ✅ Do

* Use `Behavior` for most components (serialization support)
* Initialize in `onStart()`, not the constructor
* Use `@RequiresComponent` for dependencies
* Let server make authoritative decisions
* Use batched replication when possible
* Clean up resources with `collector`

### ❌ Avoid

* Accessing components in constructor
* Modifying NetworkedVariables on client
* Using instantaneous replication for frequent updates
* Forgetting to call `super()` in constructors
* Serializing runtime state (use configuration instead)

## 💡 Quick Reference

### Common Imports

```typescript theme={null}
// Core
import { CORP } from "CORP/shared/CORP";
import { GameObject } from "CORP/shared/componentization/game-object";
import { Behavior } from "CORP/shared/componentization/behavior";

// Networking
import { NetworkObject } from "CORP/shared/networking/network-object";
import { NetworkBehavior } from "CORP/shared/networking/network-behavior";
import { NetworkedVariable } from "CORP/shared/observables/networked-observables/networked-variable";
import { RPC } from "CORP/shared/networking/RPC";

// Decorators
import { SerializeField } from "CORP/shared/serialization/serialize-field";
import RequiresComponent from "CORP/shared/componentization/decorators/requires-component";
```

### Component Template

```typescript theme={null}
import { Behavior } from "CORP/shared/componentization/behavior";
import { GameObject } from "CORP/shared/componentization/game-object";
import { SerializeField } from "CORP/shared/serialization/serialize-field";

export class MyComponent extends Behavior {
    @SerializeField
    public configValue: number = 10;

    public constructor(gameObject: GameObject) {
        super(gameObject);
    }

    public onStart(): void {
        // Initialize
    }

    public willRemove(): void {
        // Cleanup
    }

    protected getSourceScript(): ModuleScript {
        return script as ModuleScript;
    }
}
```

### NetworkBehavior Template

```typescript theme={null}
import { NetworkBehavior } from "CORP/shared/networking/network-behavior";
import { NetworkObject } from "CORP/shared/networking/network-object";
import RequiresComponent from "CORP/shared/componentization/decorators/requires-component";
import { NetworkedVariable } from "CORP/shared/observables/networked-observables/networked-variable";
import { RPC } from "CORP/shared/networking/RPC";

@RequiresComponent(NetworkObject)
export class MyNetworkBehavior extends NetworkBehavior {
    public readonly syncedValue = new NetworkedVariable<number>(0);

    public onStart(): void {
        // Initialize
    }

    @RPC.Method({
        endpoints: [RPC.Endpoint.CLIENT_TO_SERVER],
        accessPolicy: RPC.AccessPolicy.OWNER
    })
    public myRPC(): void {
        // Server logic
    }

    public willRemove(): void {
        // Cleanup
    }

    protected getSourceScript(): ModuleScript {
        return script as ModuleScript;
    }
}
```

## 🤝 Contributing

We welcome contributions! Check out the main repository for contribution guidelines.

## 📄 License

See the main repository for license information.

## 🔗 Links

* **GitHub Repository**: [MonoliskSoftware/CORP](https://github.com/MonoliskSoftware/CORP)
* **Template Repository**: [MonoliskSoftware/CORP-TEMPLATE](https://github.com/MonoliskSoftware/CORP-TEMPLATE)
* **roblox-ts**: [roblox-ts.com](https://roblox-ts.com)

***

**Ready to build amazing games with CORP!** 🚀

Start with the **[Getting Started Tutorial](./getting-started)** or explore **[Examples](./examples)** to see CORP in action.