punkfuncgames/extract-to-package

Extract to Package — Module to UPM Package Pipeline

Prerequisites

• A working module in the game that is generic (not game-specific)
• All tests passing for the module
• Load these skills: code-style, patterns, testing, project-overview

Process

Step 1: Identify Extraction Scope

Identify all files belonging to the system:

1. Scripts — all C# files for the module (services, models, configs, events, installers)
2. Tests — all EditMode and PlayMode test files
3. Assets — any ScriptableObject configs, prefabs, or resources

List every file that will move to the package.

Step 2: Analyze Dependencies

Check dependency safety:

1. Using statements — scan all files for using directives to find external dependencies
2. Assembly definition graph — use read_asmdef_graph (if available) or manually inspect asmdef references
3. Dependents — find all files that reference this module (search for the namespace and type names)

Create a dependency report:

| Direction | Assembly/Package | Required? | Action | |-----------|-----------------|-----------|--------| | This module depends on | com.punkfuncgames.log | Optional | Add as optional dependency | | This module depends on | VContainer | Required | Add as dependency | | Game code depends on | This module | Yes | Add #if guards |

Step 3: Confirm No Game-Specific Logic

Review each file for game-specific references:

• No references to game-specific types, configs, or namespaces
• No hardcoded game values (magic numbers tied to game balance)
• All behavior is configurable via constructor parameters or ScriptableObject configs
• The module could work in any Unity project

If game-specific logic is found, refactor it out before proceeding.

Step 4: Create Package Structure

Create the UPM package at Packages/com.punkfuncgames.{name}/:

Packages/com.punkfuncgames.{name}/
  package.json
  LICENSE
  README.md
  CHANGELOG.md
  Runtime/
    PunkFuncGames.{Name}/
      {all runtime code, preserving subfolder structure}
    PunkFuncGames.{Name}.asmdef
  Tests/
    EditMode/
      {all edit mode tests}
      PunkFuncGames.{Name}.Tests.EditMode.asmdef
    PlayMode/
      {all play mode tests}
      PunkFuncGames.{Name}.Tests.PlayMode.asmdef

package.json

{
  "name": "com.punkfuncgames.{name}",
  "version": "0.1.0",
  "displayName": "{Display Name}",
  "description": "{One-line description}",
  "unity": "6000.0",
  "author": {
    "name": "PunkFunc Games",
    "url": "https://github.com/punkfuncgames"
  },
  "dependencies": {},
  "keywords": [],
  "repository": {
    "type": "git",
    "url": "https://github.com/punkfuncgames/com.punkfuncgames.{name}.git"
  }
}

Runtime asmdef

{
  "name": "PunkFuncGames.{Name}",
  "rootNamespace": "PunkFuncGames.{Name}",
  "references": [],
  "includePlatforms": [],
  "excludePlatforms": [],
  "allowUnsafeCode": false,
  "overrideReferences": false,
  "precompiledReferences": [],
  "autoReferenced": true,
  "defineConstraints": [],
  "versionDefines": [
    {
      "name": "com.punkfuncgames.{name}",
      "expression": "",
      "define": "PUNKFUNC_{NAME}"
    }
  ],
  "noEngineReferences": false
}

Step 5: Move Code and Update Namespaces

1. Move all runtime code to Runtime/PunkFuncGames.{Name}/
2. Move all tests to Tests/EditMode/ and Tests/PlayMode/
3. Update namespaces from PunkFuncGames.GameTemplate.* to PunkFuncGames.{Name}.*
4. Update all using statements in moved files
5. Update asmdef references in test assemblies

Step 6: Add Guards in Game Code

For any game code that references the extracted module, add preprocessor guards:

#if PUNKFUNC_{NAME}
using PunkFuncGames.{Name};
#endif

public sealed class SomeGameService
{
#if PUNKFUNC_{NAME}
    private readonly I{Name}Service _{name}Service;
#endif

    public SomeGameService(
#if PUNKFUNC_{NAME}
        I{Name}Service {name}Service,
#endif
        IOtherService otherService)
    {
#if PUNKFUNC_{NAME}
        _{name}Service = {name}Service;
#endif
    }
}

Step 7: Run All Tests

Run the full test suite to verify nothing is broken:

1. Package tests pass in isolation
2. Game tests pass with the package present
3. No compilation errors

Step 8: Create GitHub Repository

# Create the repo
gh repo create punkfuncgames/com.punkfuncgames.{name} \
  --public \
  --description "{One-line description}" \
  --clone

# Copy package contents to the repo
cp -r Packages/com.punkfuncgames.{name}/* /path/to/cloned/repo/

# Initialize, commit, tag
cd /path/to/cloned/repo
git add .
git commit -m "feat: initial package extraction from game template"
git tag v0.1.0
git push origin main --tags

Step 9: Update Project Manifest

Update Packages/manifest.json to reference the package via git URL:

{
  "dependencies": {
    "com.punkfuncgames.{name}": "https://github.com/punkfuncgames/com.punkfuncgames.{name}.git#v0.1.0"
  }
}

Remove the local package from Packages/ since it is now referenced via git.

Step 10: Final Verification

1. Delete the local package folder (it is now fetched from git)
2. Let Unity resolve the package from the git URL
3. Run all tests again to confirm everything works with the remote package

Step 11: Commit

git add Packages/manifest.json
git add Assets/  # For any #if guard changes
git rm -r Packages/com.punkfuncgames.{name}/  # Remove local copy
git commit -m "refactor: extract {name} module to UPM package"

Output

The GitHub repo URL, package version (v0.1.0), git URL for manifest.json, and test results confirming all tests pass.