LightlessClient/DEVELOPMENT.md

Development Setup for macOS

This document explains how to set up the Lightless Sync development environment on macOS.

Problem: "Cannot resolve symbol 'Dalamud'"

When developing Dalamud plugins on macOS, you may encounter the error:

Cannot resolve symbol 'Dalamud'
Dalamud.NET.Sdk: Dalamud installation not found at /Users/.../Library/Application Support/XIV on Mac/dalamud/Hooks/dev/

This happens because the Dalamud.NET.Sdk expects to find Dalamud assemblies at a specific path, but they don't exist if you don't have XIV on Mac or Dalamud installed.

Solution

Automated Setup (Recommended)

Run the setup script to download the required Dalamud assemblies:

./setup-dalamud.sh

This script will:

1. Create a development directory at ~/.dalamud/dev
2. Download the latest Dalamud assemblies from the official distribution
3. Extract them to the development directory

Manual Setup

If you prefer to set up manually:

1. Create the Dalamud directory:

   mkdir -p ~/.dalamud/dev
   

2. Download Dalamud assemblies:

   curl -L -o /tmp/dalamud.zip https://goatcorp.github.io/dalamud-distrib/latest.zip
   unzip /tmp/dalamud.zip -d ~/.dalamud/dev
   

3. Set the DALAMUD_HOME environment variable (optional):

   export DALAMUD_HOME="$HOME/.dalamud/dev"
   

How It Works

The project includes a Directory.Build.props file that automatically configures the DALAMUD_HOME path to use ~/.dalamud/dev if it exists. This overrides the default XIV on Mac path.

The Dalamud.NET.Sdk will then use this path to find the required assemblies for compilation and IntelliSense.

Building the Project

After setup, you can build the project normally:

dotnet restore
dotnet build

IDE Configuration

JetBrains Rider / IntelliJ IDEA

After running the setup script, you may need to:

1. Invalidate caches and restart: File → Invalidate Caches → Invalidate and Restart
2. Reload the solution: Right-click on solution → Reload All Projects

The IDE should now resolve all Dalamud symbols correctly.

Troubleshooting

Build still fails with "Dalamud installation not found"

1. Verify the assemblies were downloaded:

   ls -la ~/.dalamud/dev/Dalamud.dll
   

2. Check that Directory.Build.props exists in the project root

3. Try cleaning and rebuilding:

   dotnet clean
   dotnet build
   

IDE still shows "Cannot resolve symbol 'Dalamud'"

1. Ensure the build succeeds first (run dotnet build)
2. Restart your IDE
3. Try invalidating caches (Rider/IntelliJ)
4. Check that the project references are loaded correctly

Files Modified

• Directory.Build.props - Configures DALAMUD_HOME path
• LightlessSync/LightlessSync.csproj - Removed duplicate DalamudPackager reference
• PenumbraAPI/Penumbra.Api.csproj - Added DalamudLibPath configuration
• setup-dalamud.sh - Setup script to download Dalamud assemblies

Additional Notes

• The Dalamud assemblies are only needed for development/compilation
• You don't need a running FFXIV or XIV on Mac installation to develop plugins
• The assemblies are downloaded from the official Dalamud distribution
• Updates to Dalamud may require re-running the setup script