From unity
Unity data-driven design architecture. ScriptableObject config hierarchies, JSON data pipelines, designer handoff workflows, data versioning and migration, Inspector attributes for self-documenting configs. DECISION format: WHEN/DECISION/SCAFFOLD/GOTCHA. Based on Unity 6.3 LTS.
npx claudepluginhub cdata/aria-skills --plugin unityThis skill uses the workspace's default tool permissions.
> **Prerequisite skills:** `unity-scripting/references/scriptableobjects.md` (SO creation, event channels, runtime sets, variable references), `unity-editor-tools` (custom inspectors, EditorWindow)
Guides Unity gameplay architecture patterns with clear runtime ownership, separating data/state/views from scenes/inspector wiring. Use for growing scene complexity or unclear system lifetimes.
Unity 6 core concepts and architecture guide. Use when working with GameObjects, Components, Transforms, Scenes, Prefabs, ScriptableObjects, or Unity project structure. Covers the entity-component architecture, object hierarchy, tags, layers, and project conventions. Based on Unity 6.3 LTS documentation.
Guides Unity editor scripting for custom inspectors, EditorWindows, PropertyDrawers; build pipelines, CI/CD with GameCI/GitHub Actions; Unity Test Framework; version control and packages.
Share bugs, ideas, or general feedback.
Prerequisite skills:
unity-scripting/references/scriptableobjects.md(SO creation, event channels, runtime sets, variable references),unity-editor-tools(custom inspectors, EditorWindow)
These patterns address the most common data management failure: Claude hardcodes tunable values in MonoBehaviours or uses magic numbers, making iteration and balancing painful. All game data should be designer-editable without code changes.
WHEN: Choosing where to store game configuration (enemy stats, level layouts, loot tables)
DECISION:
static readonly or const.SCAFFOLD (ScriptableObject config):
[CreateAssetMenu(fileName = "New Enemy Config", menuName = "Game/Enemy Config")]
public class EnemyConfig : ScriptableObject
{
[Header("Stats")]
[Min(1)] public int maxHealth = 100;
[Range(0f, 20f)] public float moveSpeed = 5f;
[Range(0f, 50f)] public float attackDamage = 10f;
[Header("AI")]
[Range(1f, 50f)] public float detectionRange = 15f;
[Range(0.5f, 5f)] public float attackCooldown = 1.5f;
[Header("Rewards")]
[Min(0)] public int xpReward = 25;
[Tooltip("Loot dropped on death. Leave empty for no loot.")]
public LootTable lootTable;
}
// Usage in MonoBehaviour:
public class Enemy : MonoBehaviour
{
[SerializeField] private EnemyConfig config; // Assign in Inspector
void Awake()
{
// Read from config -- never hardcode values
_health = new HealthSystem(config.maxHealth);
_moveSpeed = config.moveSpeed;
}
}
GOTCHA: ScriptableObject assets modified at runtime in the Editor persist those changes to disk (the .asset file is saved). In builds, runtime modifications are lost when the application exits. Never rely on runtime SO modification for save data -- use a separate save system. See unity-save-system for persistence.
WHEN: Multiple config types share base fields (all enemies have HP/speed, subtypes add flying/ranged/boss fields)
DECISION:
EnemyConfig : ScriptableObject, FlyingEnemyConfig : EnemyConfig. Each subtype adds its own fields. Designer sees only relevant fields per asset. Works well for 2-3 levels of hierarchy.[Serializable] structs (composition) -- EnemyConfig contains [SerializeField] MovementConfig movement; [SerializeField] AttackConfig attack;. Mix-and-match capabilities. Often cleaner than inheritance for wide variation.SCAFFOLD (Composition):
[System.Serializable]
public struct MovementConfig
{
[Range(0f, 20f)] public float speed;
public bool canFly;
[Tooltip("Only used if canFly is true")]
[Range(0f, 50f)] public float flyHeight;
}
[System.Serializable]
public struct AttackConfig
{
public AttackType type;
[Range(0f, 100f)] public float damage;
[Range(0.1f, 10f)] public float cooldown;
[Range(0f, 30f)] public float range;
}
[CreateAssetMenu(fileName = "New Enemy", menuName = "Game/Enemy Config")]
public class EnemyConfig : ScriptableObject
{
[Header("Identity")]
public string displayName;
[TextArea(2, 4)] public string description;
[Header("Movement")]
public MovementConfig movement;
[Header("Combat")]
public AttackConfig attack;
[Header("Stats")]
[Min(1)] public int maxHealth = 100;
[Min(0)] public int xpReward = 25;
}
SCAFFOLD (Inheritance):
public abstract class EnemyConfig : ScriptableObject
{
[Min(1)] public int maxHealth = 100;
[Range(0f, 20f)] public float moveSpeed = 5f;
}
[CreateAssetMenu(fileName = "New Melee Enemy", menuName = "Game/Enemies/Melee")]
public class MeleeEnemyConfig : EnemyConfig
{
[Range(0f, 50f)] public float meleeDamage = 15f;
[Range(0.5f, 3f)] public float attackRadius = 1.5f;
}
[CreateAssetMenu(fileName = "New Ranged Enemy", menuName = "Game/Enemies/Ranged")]
public class RangedEnemyConfig : EnemyConfig
{
[Range(0f, 50f)] public float projectileDamage = 10f;
[Range(5f, 30f)] public float fireRange = 15f;
public GameObject projectilePrefab;
}
GOTCHA: SO inheritance shows ALL base fields in the Inspector (no hiding). Use [HideInInspector] or a custom editor if base fields clutter the Inspector. Composition with [Serializable] structs is often cleaner because each struct can be reused across unrelated config types. [CreateAssetMenu] only works on concrete (non-abstract) ScriptableObject subclasses.
WHEN: Loading game data from external sources (spreadsheets, web APIs, modding)
DECISION:
SCAFFOLD (Runtime JSON loading):
// Data class (plain C#, not ScriptableObject)
[System.Serializable]
public class WaveData
{
public int waveNumber;
public string[] enemyTypes;
public int[] enemyCounts;
public float spawnInterval;
}
[System.Serializable]
public class WaveDataList
{
public WaveData[] waves; // JsonUtility requires a wrapper for arrays
}
// Loading
public class WaveLoader : MonoBehaviour
{
async Awaitable<WaveData[]> LoadWaves()
{
string path = Path.Combine(Application.streamingAssetsPath, "waves.json");
#if UNITY_ANDROID && !UNITY_EDITOR
// Android: StreamingAssets is inside APK, must use UnityWebRequest
using var request = UnityWebRequest.Get(path);
await request.SendWebRequest();
string json = request.downloadHandler.text;
#else
string json = await File.ReadAllTextAsync(path);
#endif
var wrapper = JsonUtility.FromJson<WaveDataList>(json);
return wrapper.waves;
}
}
GOTCHA: JsonUtility cannot serialize: dictionaries, top-level arrays (need a wrapper class), polymorphic types, null values (uses default instead), or properties (only fields). For any of these, use Newtonsoft JSON (com.unity.nuget.newtonsoft-json package). Application.streamingAssetsPath is read-only on all platforms and requires UnityWebRequest on Android. See references/data-pipeline-patterns.md for the Editor import script.
WHEN: Designers need to create and edit game data without touching code
DECISION:
SCAFFOLD (Self-documenting Inspector):
[CreateAssetMenu(fileName = "New Weapon", menuName = "Game/Weapons/Weapon Config")]
public class WeaponConfig : ScriptableObject
{
[Header("Identity")]
[Tooltip("Display name shown in UI and inventory")]
public string displayName;
[TextArea(2, 5)]
[Tooltip("Flavor text shown in the item tooltip")]
public string description;
public Sprite icon;
[Header("Combat Stats")]
[Tooltip("Base damage before modifiers. Actual damage = base * level multiplier")]
[Range(1f, 200f)] public float baseDamage = 10f;
[Tooltip("Seconds between attacks")]
[Range(0.1f, 5f)] public float attackSpeed = 1f;
[Tooltip("Maximum range in world units")]
[Range(0.5f, 30f)] public float range = 2f;
[Header("VFX/SFX")]
[Tooltip("Played on hit. Leave null for no effect")]
public GameObject hitEffect;
[Tooltip("Played on attack")]
public AudioClip attackSound;
[Space(10)]
[Header("Advanced")]
[Tooltip("Damage falloff over distance. X = normalized distance (0-1), Y = damage multiplier")]
public AnimationCurve damageFalloff = AnimationCurve.Linear(0, 1, 1, 0.5f);
}
GOTCHA: Designers cannot read code comments -- use [Tooltip("...")] on every field. Use [Range(min, max)] to prevent invalid data entry. Use [Header("Section")] to group related fields. Use [Space(10)] for visual separation. AnimationCurve fields are powerful for designer-tunable falloffs, easing, and response curves. Mark optional references with tooltips like "Leave null for no effect".
WHEN: Shipped data format changes between updates (added/renamed/removed fields)
DECISION:
int version in the data, run migration on load.SCAFFOLD (FormerlySerializedAs for renames):
using UnityEngine.Serialization;
public class EnemyConfig : ScriptableObject
{
// Renamed from "hp" to "maxHealth" -- existing assets preserved
[FormerlySerializedAs("hp")]
[Min(1)] public int maxHealth = 100;
// Renamed from "speed" to "moveSpeed"
[FormerlySerializedAs("speed")]
[Range(0f, 20f)] public float moveSpeed = 5f;
// New field -- existing assets get the default value (25)
[Min(0)] public int xpReward = 25;
// Removed field: just delete it. Existing assets silently drop the old data.
}
SCAFFOLD (Versioned runtime data with migration):
[System.Serializable]
public class PlayerData
{
public int version = 2; // Current schema version
public string playerName;
public int level;
public float[] position; // v2: changed from Vector3 to float[] for JSON compat
// Migration from v1 to v2
public static PlayerData MigrateFromV1(string json)
{
// v1 had "pos_x", "pos_y", "pos_z" as separate fields
var jObj = Newtonsoft.Json.Linq.JObject.Parse(json);
if ((int)jObj["version"] == 1)
{
float x = (float)jObj["pos_x"];
float y = (float)jObj["pos_y"];
float z = (float)jObj["pos_z"];
jObj.Remove("pos_x"); jObj.Remove("pos_y"); jObj.Remove("pos_z");
jObj["position"] = new Newtonsoft.Json.Linq.JArray(x, y, z);
jObj["version"] = 2;
}
return jObj.ToObject<PlayerData>();
}
}
GOTCHA: [FormerlySerializedAs] only works for Unity serialization (Inspector, .asset files, prefabs). It does NOT work for JSON or custom serialization. For JSON migration, you must parse the raw JSON before deserializing to the new type. SO data versioning and save data versioning are different problems -- see unity-save-system for save file migration.
| Attribute | Purpose | Example |
|---|---|---|
[Header("Section")] | Section label | Group related fields |
[Tooltip("Help text")] | Hover help text | Explain non-obvious fields |
[Range(min, max)] | Slider for numeric fields | [Range(0, 100)] |
[Min(value)] | Minimum value clamp | [Min(0)] for non-negative |
[TextArea(min, max)] | Multi-line text field | [TextArea(2, 5)] |
[Space(pixels)] | Vertical spacing | [Space(10)] |
[HideInInspector] | Hide from Inspector | Internal fields |
[FormerlySerializedAs] | Preserve data on rename | Migration safety |
[ColorUsage(alpha, hdr)] | Color picker config | [ColorUsage(true, true)] |
[GradientUsage(hdr)] | Gradient HDR support | VFX color ramps |
[Delayed] | Apply on Enter/focus loss | Prevent per-keystroke updates |
[SerializeReference] | Polymorphic serialization | Interface fields |