Idle Dyson Swarm - Claude Instructions

Project Overview

Idle Dyson Swarm is a Unity incremental/idle game where players build a network of facilities to generate science and expand across the universe.

Architecture Status

The codebase is undergoing architectural modernization. See migration documentation in:

```
Assets/Scripts/Services/README.md
```
- Service layer architecture
Phase-specific PR descriptions in git history
Planning documents in
```
Documentation/
```
folder

Common Patterns

Safe Data Access with TryGet

Always use TryGet pattern for data lookups to avoid null reference exceptions:

if (_dataService.TryGetFacility(facilityId, out var definition))
{
    // Use definition safely
    string name = definition.displayName;
}
else
{
    Debug.LogWarning($"Facility not found: {facilityId}");
}

Facility Count Access

Facilities have both auto-purchased and manually-purchased counts:

double[] counts = _facilityService.GetFacilityCount(facilityId);
double autoCount = counts[0];    // Auto-purchased
double manualCount = counts[1];  // Manually-purchased
double totalCount = autoCount + manualCount;

XML Documentation

All public APIs should have XML documentation:

/// <summary>
/// Gets the current level of a research upgrade.
/// </summary>
/// <param name="researchId">The unique identifier of the research.</param>
/// <returns>The current research level, or 0 if not researched.</returns>
public double GetResearchLevel(string researchId)
{
    // Implementation
}

Testing

Unit Tests

Test files go in
```
Assets/Tests/
```
Use
```
MockGameStateService
```
for testing presenter logic without Oracle dependency
Follow AAA pattern (Arrange, Act, Assert):

[Test]
public void Science_CanBeModified()
{
    // Arrange
    _mockGameState.SetScience(1000);

    // Act
    _mockGameState.Science -= 500;

    // Assert
    Assert.AreEqual(500, _mockGameState.Science);
}

Manual Testing

Open the Game scene
Run the game
Verify facility purchasing works
Verify research purchasing works
Check Unity Console for errors

Console Log Buffer (No MCP)

For agent-friendly console access, a lightweight Editor script writes a JSON snapshot of recent logs.

Output file:

Documentation/Console/editor-console.json

Controls (Unity menu):

Tools/Console Log Buffer/Filter/Include Logs

Tools/Console Log Buffer/Filter/Include Warnings

Tools/Console Log Buffer/Filter/Include Errors

```
Tools/Console Log Buffer/Clear
```

Behavior:

Keeps last 1000 entries in memory.
Writes a filtered snapshot to the JSON file when new logs arrive.
Clears on Editor restart/domain reload (static init).

Common Errors & Solutions

Missing Typed ID Using Directive

Error:

CS0246: The type or namespace name 'FacilityId' could not be found

Solution: Add

using IdleDysonSwarm.Data;

Out Parameter Not Assigned

Error:

CS0177: The out parameter 'definition' must be assigned before control leaves the current method

Solution: Initialize out parameter to null at start of method:

public bool TryGetFacility(string id, out FacilityDefinition definition)
{
    definition = null; // Initialize first
    return _registry != null && _registry.TryGetFacility(id, out definition);
}

Property Casing Issues

Error:

CS1061: 'DysonVerseInfinityData' does not contain a definition for 'datacenters'

Solution: Use correct casing (camelCase for fields/properties):

dataCenters

not

datacenters

Git Workflow

Full documentation: See

.claude/git-workflow.md

for comprehensive git rules.

Core Rules

Never work directly on main - Always create a feature/refactor/fix branch first
Commit after each phase - Atomic commits representing logical units of work
Feature parity required - Refactors must not break existing functionality
No broken saves - Save compatibility must be verified before merging
PR for every merge - All changes reach main through pull requests
NEVER use
git reset --hard
without asking - This command destroys uncommitted changes permanently. Always ask the user for confirmation before running any destructive git commands (
```
reset --hard
```
,
```
clean -fd
```
,
```
checkout .
```
, etc.)

Branch Naming

```
feature/description
```
- New functionality
```
refactor/description
```
- Code restructuring (behavior unchanged)
```
fix/description
```
- Bug fixes
```
phase/N-description
```
- Multi-part architectural changes

Commit Messages

Follow conventional commits (imperative mood):

feat: Add service layer foundation
refactor: Migrate FacilityBuildingPresenter to use services
fix: Resolve compilation errors in GameDataService
docs: Add comprehensive README for service layer
test: Add unit tests for mock service layer

Add

Co-Authored-By

trailer to commits when Claude contributed to the changes:

Co-Authored-By: Claude Opus 4.6 <[email protected]>

Pre-PR Code Simplification

Before creating a PR, run the

code-simplify

agent on all modified files.

The agent will:

Identify and remove dead code, unused variables, and redundant patterns
Flag over-abstraction and unnecessary complexity
Suggest control flow improvements
Report findings by confidence level

This ensures PRs are clean and don't introduce unnecessary complexity.

Before Merging to Main

Code compiles without errors
Code simplification agent has been run on changed files
Existing functionality unchanged (for refactors)
Save compatibility verified with existing saves
PR created with summary of changes

Pull Request Descriptions

Include:

Summary of changes
Testing checklist (compilation, save compatibility)
Breaking changes (if any)

Skills

Global skills are stored in

~/.claude/skills/

and are available across all projects. Project-level skills go in

.claude/skills/

create-pr
(global:
```
~/.claude/skills/create-pr/SKILL.md
```
) - Commit, push, create PR, and optionally merge in one step

Clarifying Questions (Required)

Do not make assumptions. If a request, requirement, expected behavior, acceptance criteria, asset reference, platform target, build step, or test/verification approach is ambiguous or underspecified, stop and ask the user clarifying questions before changing code/content. If multiple interpretations are plausible, enumerate them briefly and ask which one is intended.

Important Rules

Code Quality

Always read files first - Never propose changes to code you haven't read
Preserve behavior - Don't change runtime behavior unless explicitly requested
XML documentation - Document all public APIs
Follow naming conventions - See Code Style section above
Test compilation - Always verify changes compile successfully
Avoid modifying third-party code under
```
Assets/Plugins/
```
unless explicitly requested

Service Layer (Modern Code)

Use services over Oracle - Inject services via ServiceLocator in Awake()
Interface first - Define interfaces before implementations
Safe access patterns - Use TryGet pattern with out parameters
Null safety - Always initialize out parameters before early returns

Legacy Code (Oracle)

Qualify nested types - Use
```
Oracle.BuyMode
```
,
```
Oracle.textColourBlue
```
Know data access patterns - PrestigePlus via StaticSaveSettings, Secrets via ModifierSystem
Avoid breaking changes - Oracle code still used throughout codebase

Documentation Maintenance (Required)

When editing any script (C# under

Assets/Scripts/**

Assets/Editor/**

, plus any build/tooling scripts in-repo), do a documentation pass as part of the same change.

If the code is unclear, do not guess. Use repo search to find who calls it / what it calls, inspect referenced assets (ScriptableObjects, prefabs, scenes), and then document what you learned in that same edit.

Minimum Per-Script Documentation Standard

In the file being edited:

Header comment: purpose, where it runs (runtime/editor), primary entry points (Unity event methods, menu items, callbacks), what it owns vs delegates.
Interacts with: key classes/services it calls, and key callers that invoke it (paths/class names).
Change notes: what breaks if you change public methods, events, serialized fields, save keys, or ScriptableObject IDs; list the other places/assets that must be updated together.

Complex/Central Scripts

Also add/refresh a companion doc under

Documentation/Code/

named after the script/class. That doc should capture: contract/behavior expectations, data flow, save/load implications, performance pitfalls, and quick verification steps.

Structural Changes

When adding a new system/service/subsystem, renaming/moving script folders, or changing how major systems connect, update

AGENTS.md

(and

STRUCTURE.md

when it's a structural change) in the same PR.

Do not do "documentation cleanup" inside

Assets/Plugins/**

unless explicitly requested; instead document integration points and expectations in our code.

Steam Build/Upload (Windows)

When asked to do a Windows Steam build/upload for Idle Dyson Swarm:

Ensure the Windows build output exists at

C:\Users\mattr\Documents\Unity\Builds\IdleDysonSwarm

Upload via SteamCMD using

C:\Users\mattr\Documents\steamcmd\Scripts\upload_idle_dyson_swarm_windows.bat

Steam AppID:
```
4348570
```
, Windows depot:
```
4348571
```
.

SteamCMD VDFs live at:

C:\Users\mattr\Documents\steamcmd\Scripts\app_build_4348570_windows.vdf

C:\Users\mattr\Documents\steamcmd\Scripts\depot_build_4348571_windows.vdf

Resources

Service Layer: See
```
Assets/Scripts/Services/README.md
```
Migration Plans: Check git history for phase documentation

Testing Patterns: See

Assets/Tests/Services/ServiceLayerExampleTests.cs

Project Map: See
```
AGENTS.md
```
and
```
STRUCTURE.md
```

Questions?

When in doubt:

Check relevant README files in the specific subsystem
Look at existing implementations for patterns
Ask the user for clarification on project-specific decisions

Idle Dyson Swarm - Claude Instructions

Project Overview

Idle Dyson Swarm is a Unity incremental/idle game where players build a network of facilities to generate science and expand across the universe.

Architecture Status

The codebase is undergoing architectural modernization. See migration documentation in:

```
Assets/Scripts/Services/README.md
```
- Service layer architecture
Phase-specific PR descriptions in git history
Planning documents in
```
Documentation/
```
folder

Code Style & Conventions

Naming Conventions

Classes: PascalCase (e.g.,

FacilityBuildingPresenter

GameStateService

)

Interfaces: PascalCase with
```
I
```
prefix (e.g.,
```
IGameStateService
```
,
```
IFacilityService
```
)
Private fields: camelCase with
```
_
```
prefix (e.g.,
```
_gameState
```
,
```
_facilityService
```
)
Public properties: PascalCase (e.g.,
```
Science
```
,
```
InfinityData
```
)
Methods: PascalCase (e.g.,
```
GetResearchLevel
```
,
```
TryGetFacility
```
)
Parameters: camelCase (e.g.,
```
researchId
```
,
```
facilityId
```
)
Constants: PascalCase (e.g.,
```
Oracle.textColourBlue
```
)

Typed IDs

The project uses typed ID wrappers to prevent ID mixing errors:

using IdleDysonSwarm.Data;

FacilityId facilityId = new FacilityId("assembly_lines");
SkillId skillId = new SkillId("faster_production");
ResearchId researchId = new ResearchId("science_boost");

Key points:

Always use typed IDs instead of raw strings when working with facilities, skills, research, and effects
IDs are in the
```
IdleDysonSwarm.Data
```
namespace
IDs have implicit conversions to/from string for backward compatibility

Service Layer Pattern

Always prefer services over direct Oracle access:

// ❌ Old pattern (avoid in new code)
using static Expansion.Oracle;
double science = StaticInfinityData.Science;

// ✅ New pattern (use this)
using IdleDysonSwarm.Services;
private IGameStateService _gameState;

private void Awake()
{
    _gameState = ServiceLocator.Get<IGameStateService>();
}

private void UpdateUI()
{
    double science = _gameState.Science;
}

Available Services:

```
IGameStateService
```
- Core game state (InfinityData, PrestigeData, SkillTreeData, Science, Research)
```
IGameDataService
```
- Definition data (facilities, skills, research, effects)
```
IFacilityService
```
- Facility management operations

Service registration:

Services are auto-registered by
```
ServiceProvider
```
MonoBehaviour at startup
Use
```
ServiceLocator.Get<TService>()
```
in
```
Awake()
```
to inject dependencies
See
```
Assets/Scripts/Services/README.md
```
for detailed documentation

Scriptable Conditions

Use scriptable conditions for unlock/visibility logic instead of hardcoded checks:

// ❌ Old pattern (hardcoded logic)
if (StaticInfinityData.assemblyLines[0] >= 10 && StaticPrestigeData.hasUnlockedX)
{
    // Show UI element
}

// ✅ New pattern (scriptable conditions)
[SerializeField] private ScriptableCondition unlockCondition;

private void UpdateUI()
{
    if (unlockCondition != null && unlockCondition.IsMet())
    {
        // Show UI element
    }
}

Benefits:

Design unlock logic in Unity Inspector
No code changes for balance adjustments
Composable with AND/OR/NOT operators

Oracle Singleton

The

Oracle

class is a legacy static singleton being phased out:

Current state:

Production code still uses Oracle directly via
```
using static Expansion.Oracle;
```
New presenter code should use services instead
When working with Oracle nested types, use full qualification:

// Nested enums
Oracle.BuyMode mode = Oracle.BuyMode.Buy1;

// Color constants
string text = $"{Oracle.textColourBlue}Science</color>";

Data access patterns:

PrestigePlus

: Access via

Oracle.StaticSaveSettings.prestigePlus

(not StaticPrestigePlus)

SecretBuffState

: Build via

ModifierSystem.BuildSecretBuffState(Oracle.StaticPrestigeData)

(not StaticSecrets)

Project Structure

Root

```
Assets/
```
Unity assets, code, scenes, prefabs, plugins.
```
Packages/
```
Unity package manifest + lock data.
```
ProjectSettings/
```
Unity project configuration.
```
Library/
```
,
```
Temp/
```
,
```
Logs/
```
,
```
UserSettings/
```
generated Unity output (not source).
```
Documentation/
```
project docs, plans, and references.
```
Documentation/Code/
```
(create as needed) design/contract notes for complex or central scripts.
```
Recordings/
```
image sequences and captures.
```
STRUCTURE.md
```
additional high-level project map.
```
UIElementsSchema/
```
UIElements schema assets.
```
steam_appid.txt
```
Steam AppID for local runs.

Assets (Scripts)

Assets/Scripts/
├── Buildings/              # Building logic and presenters
├── Classes/                # Shared classes and helpers
├── Conditions/             # Scriptable conditions (Phase 2)
├── Data/                   # ScriptableObject definitions, typed IDs, condition system
├── Editor/                 # Editor-side code in the Scripts tree
├── Expansion/              # Oracle, research, Dream1 era logic
├── Incremental/            # Incremental game loop logic
├── NewsTicker/             # News feed handling
├── Research/               # Research UI helpers
├── Services/               # Service layer + service locator
├── SkillTreeStuff/         # Skill tree logic and UI
├── Systems/                # Core gameplay systems, stats, facilities, migrations, platform, audio
├── UI/                     # UI theme and simulation types
├── UnityPurchasing/        # In-app purchase integration
├── User Interface/         # UI panels, toggles, side-panel logic
└── Blindsided/Utilities/   # Shared utility components

Assets (Other)

```
Assets/Scenes/
```
game scenes (
```
Load.unity
```
,
```
Game.unity
```
).
```
Assets/Data/
```
top-level ScriptableObjects and config assets.

Assets/Prefabs/

prefab variants (notably

Assets/Prefabs/Buildings/

```
Assets/Presets/
```
Unity presets.
```
Assets/Resources/
```
runtime resources (IAP catalog, audio).
```
Assets/Editor/
```
editor tooling and validation helpers.
```
Assets/Editor Default Resources/
```
editor-only assets.
```
Assets/Plugins/
```
third-party plugins (Easy Save 3, Sirenix, Google Play Games, etc.).
```
Assets/ExternalDependencyManager/
```
EDM4U Google dependency manager.
```
Assets/KeyStore/
```
Android keystore material.
```
Assets/Extensions/
```
platform extensions (Google Play Games, etc.).

Assets/MPUIKit/

Assets/TextMesh Pro/

Assets/Fonts/

Assets/Sprites/

Assets/Sounds/

UI + art assets.

Documentation

Documentation/ALLACHIEVEMENTS.md

and

Documentation/AchievementIdeas.md

```
Documentation/AchievementPackageForEve/
```
achievement package materials.
```
Documentation/Archive/
```
legacy plans, refactors, and notes.
```
Documentation/SaveBackups/
```
save data backups.
```
Documentation/savedebugging/
```
save debugging notes.

Documentation/Console/editor-console.json

Unity Editor log snapshot for agents.

Common Patterns

Safe Data Access with TryGet

Always use TryGet pattern for data lookups to avoid null reference exceptions:

if (_dataService.TryGetFacility(facilityId, out var definition))
{
    // Use definition safely
    string name = definition.displayName;
}
else
{
    Debug.LogWarning($"Facility not found: {facilityId}");
}

Facility Count Access

Facilities have both auto-purchased and manually-purchased counts:

double[] counts = _facilityService.GetFacilityCount(facilityId);
double autoCount = counts[0];    // Auto-purchased
double manualCount = counts[1];  // Manually-purchased
double totalCount = autoCount + manualCount;

XML Documentation

All public APIs should have XML documentation:

/// <summary>
/// Gets the current level of a research upgrade.
/// </summary>
/// <param name="researchId">The unique identifier of the research.</param>
/// <returns>The current research level, or 0 if not researched.</returns>
public double GetResearchLevel(string researchId)
{
    // Implementation
}

Testing

Unit Tests

Test files go in
```
Assets/Tests/
```
Use
```
MockGameStateService
```
for testing presenter logic without Oracle dependency
Follow AAA pattern (Arrange, Act, Assert):

[Test]
public void Science_CanBeModified()
{
    // Arrange
    _mockGameState.SetScience(1000);

    // Act
    _mockGameState.Science -= 500;

    // Assert
    Assert.AreEqual(500, _mockGameState.Science);
}

Manual Testing

Open the Game scene
Run the game
Verify facility purchasing works
Verify research purchasing works
Check Unity Console for errors

Console Log Buffer (No MCP)

For agent-friendly console access, a lightweight Editor script writes a JSON snapshot of recent logs.

Output file:

Documentation/Console/editor-console.json

Controls (Unity menu):

Tools/Console Log Buffer/Filter/Include Logs

Tools/Console Log Buffer/Filter/Include Warnings

Tools/Console Log Buffer/Filter/Include Errors

```
Tools/Console Log Buffer/Clear
```

Behavior:

Keeps last 1000 entries in memory.
Writes a filtered snapshot to the JSON file when new logs arrive.
Clears on Editor restart/domain reload (static init).

Common Errors & Solutions

Missing Typed ID Using Directive

Error:

CS0246: The type or namespace name 'FacilityId' could not be found

Solution: Add

using IdleDysonSwarm.Data;

Oracle Nested Type Not Found

Error:

CS0103: The name 'BuyMode' does not exist in the current context

Solution: Use

Oracle.BuyMode

instead of

BuyMode

(or add

using static Expansion.Oracle;

)

Out Parameter Not Assigned

Error:

CS0177: The out parameter 'definition' must be assigned before control leaves the current method

Solution: Initialize out parameter to null at start of method:

public bool TryGetFacility(string id, out FacilityDefinition definition)
{
    definition = null; // Initialize first
    return _registry != null && _registry.TryGetFacility(id, out definition);
}

Property Casing Issues

Error:

CS1061: 'DysonVerseInfinityData' does not contain a definition for 'datacenters'

Solution: Use correct casing (camelCase for fields/properties):

dataCenters

not

datacenters

Git Workflow

Full documentation: See

.claude/git-workflow.md

for comprehensive git rules.

Core Rules

Never work directly on main - Always create a feature/refactor/fix branch first
Commit after each phase - Atomic commits representing logical units of work
Feature parity required - Refactors must not break existing functionality
No broken saves - Save compatibility must be verified before merging
PR for every merge - All changes reach main through pull requests
NEVER use
git reset --hard
without asking - This command destroys uncommitted changes permanently. Always ask the user for confirmation before running any destructive git commands (
```
reset --hard
```
,
```
clean -fd
```
,
```
checkout .
```
, etc.)

Branch Naming

```
feature/description
```
- New functionality
```
refactor/description
```
- Code restructuring (behavior unchanged)
```
fix/description
```
- Bug fixes
```
phase/N-description
```
- Multi-part architectural changes

Commit Messages

Follow conventional commits (imperative mood):

feat: Add service layer foundation
refactor: Migrate FacilityBuildingPresenter to use services
fix: Resolve compilation errors in GameDataService
docs: Add comprehensive README for service layer
test: Add unit tests for mock service layer

Add

Co-Authored-By

trailer to commits when Claude contributed to the changes:

Co-Authored-By: Claude Opus 4.6 <[email protected]>

Pre-PR Code Simplification

Before creating a PR, run the

code-simplify

agent on all modified files.

The agent will:

Identify and remove dead code, unused variables, and redundant patterns
Flag over-abstraction and unnecessary complexity
Suggest control flow improvements
Report findings by confidence level

This ensures PRs are clean and don't introduce unnecessary complexity.

Before Merging to Main

Code compiles without errors
Code simplification agent has been run on changed files
Existing functionality unchanged (for refactors)
Save compatibility verified with existing saves
PR created with summary of changes

Pull Request Descriptions

Include:

Summary of changes
Testing checklist (compilation, save compatibility)
Breaking changes (if any)

Skills

Global skills are stored in

~/.claude/skills/

and are available across all projects. Project-level skills go in

.claude/skills/

create-pr
(global:
```
~/.claude/skills/create-pr/SKILL.md
```
) - Commit, push, create PR, and optionally merge in one step

Clarifying Questions (Required)

Important Rules

Code Quality

Always read files first - Never propose changes to code you haven't read
Preserve behavior - Don't change runtime behavior unless explicitly requested
XML documentation - Document all public APIs
Follow naming conventions - See Code Style section above
Test compilation - Always verify changes compile successfully
Avoid modifying third-party code under
```
Assets/Plugins/
```
unless explicitly requested

Service Layer (Modern Code)

Use services over Oracle - Inject services via ServiceLocator in Awake()
Interface first - Define interfaces before implementations
Safe access patterns - Use TryGet pattern with out parameters
Null safety - Always initialize out parameters before early returns

Legacy Code (Oracle)

Qualify nested types - Use
```
Oracle.BuyMode
```
,
```
Oracle.textColourBlue
```
Know data access patterns - PrestigePlus via StaticSaveSettings, Secrets via ModifierSystem
Avoid breaking changes - Oracle code still used throughout codebase

Documentation Maintenance (Required)

When editing any script (C# under

Assets/Scripts/**

Assets/Editor/**

, plus any build/tooling scripts in-repo), do a documentation pass as part of the same change.

Minimum Per-Script Documentation Standard

In the file being edited:

Header comment: purpose, where it runs (runtime/editor), primary entry points (Unity event methods, menu items, callbacks), what it owns vs delegates.
Interacts with: key classes/services it calls, and key callers that invoke it (paths/class names).
Change notes: what breaks if you change public methods, events, serialized fields, save keys, or ScriptableObject IDs; list the other places/assets that must be updated together.

Complex/Central Scripts

Also add/refresh a companion doc under

Documentation/Code/

named after the script/class. That doc should capture: contract/behavior expectations, data flow, save/load implications, performance pitfalls, and quick verification steps.

Structural Changes

When adding a new system/service/subsystem, renaming/moving script folders, or changing how major systems connect, update

AGENTS.md

(and

STRUCTURE.md

when it's a structural change) in the same PR.

Do not do "documentation cleanup" inside

Assets/Plugins/**

unless explicitly requested; instead document integration points and expectations in our code.

Steam Build/Upload (Windows)

When asked to do a Windows Steam build/upload for Idle Dyson Swarm:

Ensure the Windows build output exists at

C:\Users\mattr\Documents\Unity\Builds\IdleDysonSwarm

Upload via SteamCMD using

C:\Users\mattr\Documents\steamcmd\Scripts\upload_idle_dyson_swarm_windows.bat

Steam AppID:
```
4348570
```
, Windows depot:
```
4348571
```
.

SteamCMD VDFs live at:

C:\Users\mattr\Documents\steamcmd\Scripts\app_build_4348570_windows.vdf

C:\Users\mattr\Documents\steamcmd\Scripts\depot_build_4348571_windows.vdf

Resources

Service Layer: See
```
Assets/Scripts/Services/README.md
```
Migration Plans: Check git history for phase documentation

Testing Patterns: See

Assets/Tests/Services/ServiceLayerExampleTests.cs

Project Map: See
```
AGENTS.md
```
and
```
STRUCTURE.md
```

Questions?

When in doubt:

Check relevant README files in the specific subsystem
Look at existing implementations for patterns
Ask the user for clarification on project-specific decisions

Idle Dyson Swarm - Claude Instructions

Related Skills

Markdown Converter

Nano Banana Pro

1password