Canley Utilities

Quick Start

3 min read

🚀 Quick Start Guide

This guide walks you through setting up your first data schema, preparing your spreadsheet, and loading your records into memory using CSV Standard.

Step 0: Assembly Definitions

If your project uses Assembly Definitions, your scripts won’t be able to see the CSV Standard suite by default.

  • Navigate to your project’s .asmdef file.
  • Add a reference to Canley.Utility.CSV.Standard (and ensure Canley.Utility.CSV is also referenced) to unlock the namespaces.

Step 1: Define Your Data Schema

Create a class that inherits from CSVRecord. The framework automatically maps CSV columns to public fields for all supported types. For assets like Sprites that cannot be stored as raw text, use private caches and the Shadow Dictionary.

using UnityEngine;
using System;
using Canley.Utility.CSV.Standard;
 
namespace Canley.Utility.CSV.Demo
{
    public enum ItemType { Weapon, Coin, Potion, Resource }
 
    [Serializable]
    public class ItemRecord : CSVRecord
    {
        [Header("Automatically Mapped")]
        public string itemName;
        public ItemType itemType;
        public int quantity;
        public int value;
        public float weight;
        public bool isStackable;
        public Color rarityColor;
 
        [Header("Manual Asset Bridge")]
        private Sprite _cachedIcon;
 
        /// <summary>
        /// Inbound Hook: Automatically loads the Sprite from Resources the moment the CSV is loaded into memory.
        /// </summary>
        public override string OnImportField(string fieldName, string rawValue)
        {
            if (fieldName == "iconName" && !string.IsNullOrEmpty(rawValue))
            {
                _cachedIcon = Resources.Load<Sprite>($"Icons/{rawValue}");
                return base.OnImportField(fieldName, rawValue);
            }
            return base.OnImportField(fieldName, rawValue);
        }
 
        public Sprite GetIcon() => _cachedIcon;
    }
}

Step 2: Prepare the Data File

In your spreadsheet, the first row defines your data structure.

Data Sample

  • Map Your Variables: Name your column headers to match your C# variable names exactly (e.g., value, weight, isStackable).
  • The Slug (Natural Key): Use the recordLabel column as a human-friendly slug for your item (e.g., item_pot_health_01). While handy for scanning spreadsheets and string-based lookups, remember that the underlying id integer remains your true surrogate primary key.
  • Define Enums: Enter the string name of the enum into the cell; the system parses it automatically.
  • Utilize Shadow Columns: You may add extra columns (like iconName or designer notes) even if your script doesn’t have matching variables. The Shadow Dictionary preserves this hidden data automatically.

Step 3: Initialisation & Loading

Initialise the table and pull data through the CanleyCSVManager.

using UnityEngine;
using Canley.Utility.CSV;
using Canley.Utility.CSV.Standard;
using Canley.Utility.CSV.Demo;
 
public class ItemLoaderDemo : MonoBehaviour
{
    public CanleyCSVManager csvManager;
 
    private void Start()
    {
        // 1. Setup the Table
        CSVTable<ItemRecord> itemTable = new CSVTable<ItemRecord>();
 
        // 2. Load (Populates the Records list and Shadow Dictionary)
        itemTable.Load(csvManager);
 
        // 3. Dynamic Access
        foreach (ItemRecord record in itemTable.Records)
        {
            Debug.Log($"Found: {record.itemName} (Slug: {record.recordLabel})");
        }
 
        // 4. Targeted Access (Using the Slug)
        string lootSlug = "item_pot_health_01";
        ItemRecord droppedItem = itemTable.GetRecord(lootSlug);
        
        if (droppedItem != null)
        {
            Debug.Log($"Dropped item value: {droppedItem.value} (True ID: {droppedItem.id})");
        }
    }
}

NOTE

By following this workflow, you turn a simple text file into a Game Database. Your code remains clean because CSV Standard handles the parsing, while the Shadow Dictionary ensures your extra data remains safe even if you haven’t written the C# variables for it yet.

Graph View