Unity Project Setup

Docs / Getting started / Unity project setup

Recommended project configuration for ZenECS Unity projects.

Overview

Setting up a Unity project for ZenECS involves:

Assembly Definitions: Optional but recommended
Scripting Runtime: .NET Standard 2.1 or .NET 4.x
Player Settings: Scripting defines and API compatibility
Project Structure: Organize code and assets

Assembly Definitions

Why Use Assembly Definitions?

Faster compilation: Only recompile changed assemblies
Better organization: Logical code grouping
Dependency management: Clear assembly references

Recommended Structure

Assets/
├── Scripts/
│   ├── Game.asmdef          # Your game code
│   ├── Systems/             # ECS systems
│   ├── Components/          # Component definitions
│   └── ...
└── Packages/
    ├── com.zenecs.core/
    └── com.zenecs.adapter.unity/

Create Assembly Definition

Right-click folder → Create → Assembly Definition
Name it (e.g., Game.asmdef)
Add references:
- ZenECS.Core
- ZenECS.Adapter.Unity

Example asmdef:

{
    "name": "Game",
    "references": [
        "ZenECS.Core",
        "ZenECS.Adapter.Unity"
    ],
    "includePlatforms": [],
    "excludePlatforms": [],
    "allowUnsafeCode": false,
    "overrideReferences": false,
    "precompiledReferences": [],
    "autoReferenced": true,
    "defineConstraints": [],
    "versionDefines": [],
    "noEngineReferences": false
}

Scripting Runtime

.NET Standard 2.1 (Recommended)

Player Settings → Other Settings → Api Compatibility Level:

Set to .NET Standard 2.1

Benefits:

Better performance
Modern C# features
Cross-platform compatibility

.NET 4.x (Alternative)

If you need .NET 4.x features:

Set to .NET 4.x
ZenECS works with both

Player Settings

Scripting Define Symbols

Optional defines (auto-detected):

ZENECS_UNIRX - UniRx integration
ZENECS_ZENJECT - Zenject integration

Other Settings

Scripting Backend: IL2CPP or Mono (both supported)
Api Compatibility Level: .NET Standard 2.1 (recommended)
Allow 'unsafe' Code: Not required for ZenECS

Project Structure

Recommended Layout

Assets/
├── Scripts/
│   ├── Components/          # Component definitions
│   │   ├── Position.cs
│   │   └── Velocity.cs
│   ├── Systems/            # ECS systems
│   │   ├── MovementSystem.cs
│   │   └── HealthSystem.cs
│   ├── Bootstrap/          # Game initialization
│   │   └── GameBootstrap.cs
│   └── Game.asmdef
├── Prefabs/                # Entity prefabs
├── Blueprints/             # EntityBlueprint assets
└── Scenes/                 # Game scenes