Skip to content

csharp-quick-start.md

Latest commit

 

History

History
68 lines (46 loc) · 4.33 KB

csharp-quick-start.md

File metadata and controls

68 lines (46 loc) · 4.33 KB
Raw

C# (Unity) Quick Start Guide

This guide provides a rapid introduction to integrating and using the AgentSimMiddleware with a Unity project. It focuses on the minimal steps required to get a basic simulation up and running, demonstrating how to bridge the C# Unity environment with the native C++ simulation core.

Prerequisites

  • A Unity project (version 2021.3 or newer recommended).
  • The AgentSimMiddleware C++ DLL (dynamic link library) for your target platform. Follow the C++ Core Build Instructions to compile it.

Integration Steps

1. Copy C# Files to Unity Project

Copy the following essential C# files from AgentSimMiddleware/src/csharp/ into your Unity project's Assets folder (e.g., Assets/AgentSimMiddleware/Scripts/):

  • UnityAdapter.cs (Handles P/Invoke calls to the C++ DLL)
  • AgentBehaviour.cs (Example script for agents in Unity)
  • SimulationManager.cs (Orchestrates the simulation in Unity)
  • SimulationSettings.cs (ScriptableObject for simulation configuration)
  • DataStructures.cs (Core data types shared between C# and C++)
  • AgentCommand.cs (Defines commands agents send to Unity)
  • WorldSnapshot.cs (Defines the world state structure)
  • WorldSnapshotMarshaler.cs (Helper for marshaling WorldSnapshots)
  • AgentDebugVisualizer.cs (For in-editor debugging, if desired)
  • DebugSettings.cs (Debug toggles for visualizations)
  • DebugUI.cs (UI Toolkit integration for debug toggles)

2. Copy C++ DLL to Unity Project

Place the compiled C++ DLL (e.g., AgentSimMiddleware.dll for Windows) into your Unity project's Assets/Plugins/ folder. Unity will automatically manage its loading.

3. Prepare GOAP Data

The C++ simulation core uses JSON files to define agent goals and actions.

  1. Copy AgentSimMiddleware/data/actions_goals.json into your Unity project's Assets/Resources/ folder (you may need to create this folder if it doesn't exist). This file defines the GOAP logic for your agents.

4. Configure Simulation Settings

Create a SimulationSettings ScriptableObject to manage your simulation parameters.

  1. In the Unity Editor, right-click in your Project window -> Create -> AgentSim -> Simulation Settings. Name this asset QuickStartSimulationSettings.
  2. Select QuickStartSimulationSettings in the Project window and configure its properties in the Inspector:
    • Max Agents: Set a reasonable number (e.g., 100).
    • GOAP Json File Path: Set this to actions_goals (matching the file you copied in Step 3).
    • Agent Prefab: Create a simple 3D GameObject (e.g., a Cube or Sphere), turn it into a Prefab, and drag that Prefab here. This will be the visual representation of your agents.
    • Adjust Full Simulation Distance and Lite Simulation Distance as desired for LOD.

5. Setup Simulation Manager in Scene

The SimulationManager MonoBehaviour orchestrates the entire simulation within Unity.

  1. Create an empty GameObject in your Unity scene (e.g., GameObject -> Create Empty) and name it SimulationManagerObject.
  2. Add the SimulationManager.cs script to this new GameObject (Add Component -> search for Simulation Manager).
  3. Drag your QuickStartSimulationSettings asset from the Project window to the Settings field of the SimulationManager component in the Inspector.
  4. (Optional for Debug UI) Add a UIDocument component to the SimulationManagerObject (Add Component -> search for UI Document). Drag the DebugUI.uxml file (found in Assets/AgentSimMiddleware/UI/) to its Source Asset field. This will enable in-editor toggles for debug visualizations.

6. Run the Simulation

  1. Save your Unity scene.
  2. Press the Play button in the Unity Editor.

You should observe the following:

  • Debug messages in the Unity console confirming the C++ simulation's initialization.
  • The specified number of agent prefabs instantiated in your scene, moving and reacting according to the loaded GOAP logic.
  • If enabled in SimulationSettings, debug visualizations will be active in the Scene view (e.g., agent IDs, states, LOD tiers).

This quick start guides you through the essential setup. For more advanced configurations and detailed API usage, refer to the Unity Integration Guide and the C++ Core API Reference.