Настройка Google Sheets

Узнайте, как структурировать Google Sheets для генерации конфигураций C4G.

Обзор

C4G читает данные из Google Sheets и генерирует:

• C#-классы DTO (Data Transfer Objects)
• JSON-файлы конфигурации

Каждый лист в таблице становится отдельным классом конфигурации.

Создание первой таблицы конфигов

Шаг 1: Создание Google-таблицы

1. Перейдите в Google Sheets

2. Нажмите «+ Пустой» для создания новой таблицы

3. Назовите таблицу:

   • Пример: GameConfigs
   • Пример: ProductionConfigs

4. Скопируйте ID таблицы из URL:

   https://docs.google.com/spreadsheets/d/SPREADSHEET_ID_HERE/edit

   ID — это длинная строка между /d/ и /edit

Шаг 2: Структура листа

C4G ожидает определённую структуру листа:

Обязательный формат

FieldName	FieldType	Values1	Values2	Values3
id	int	1	2	3
name	string	Sword	Shield	Potion
price	float	100.5	200.0	50.75
damage	int	25	0	0

Структура столбцов:

• Столбец A (FieldName): Имена полей данных
• Столбец B (FieldType): C#-тип каждого поля
• Столбцы C и далее: Значения данных (каждый столбец — один элемент/строка данных)

Шаг 3: Поддерживаемые типы данных

C4G поддерживает следующие типы «из коробки»:

Примитивные типы

Тип	Примеры значений	Описание
int	1, 42, -5	Целые числа
float	1.5, 3.14, -2.7	Числа с плавающей точкой
double	1.5, 3.14159265	Числа двойной точности
bool	true, false	Логические значения
string	Hello, Item Name	Текстовые строки

Списки

Для создания поля-списка добавьте [] к типу:

FieldName	FieldType	Values1	Values2
tags	string[]	fire,sword	defense,metal
stats	int[]	10,20,30	5,15,25

Списки используют значения, разделённые запятыми.

Перечисления (Enums)

Сначала определите перечисление в C#:

public enum ItemRarity
{
    Common,
    Rare,
    Epic,
    Legendary
}

Затем используйте его в таблице:

FieldName	FieldType	Values1	Values2
rarity	ItemRarity	Common	Epic

Важно: Зарегистрируйте пользовательские перечисления в настройках C4G (описано в разделе «Рабочий процесс в редакторе»).

Пример: Полный конфиг предметов

Структура Google Sheet

Название листа: Items

FieldName	FieldType	Values1	Values2	Values3
id	int	1	2	3
name	string	Iron Sword	Oak Shield	Health Potion
description	string	A sturdy blade	Wooden defense	Restores HP
price	float	150.0	100.0	25.5
damage	int	25	0	0
defense	int	0	15	0
isConsumable	bool	false	false	true
tags	string[]	weapon,melee	armor,shield	consumable,heal

Сгенерированный C#-класс

C4G сгенерирует:

[System.Serializable]
public class Items
{
    public int id;
    public string name;
    public string description;
    public float price;
    public int damage;
    public int defense;
    public bool isConsumable;
    public string[] tags;
}

Сгенерированный JSON

{
  "items": [
    {
      "id": 1,
      "name": "Iron Sword",
      "description": "A sturdy blade",
      "price": 150.0,
      "damage": 25,
      "defense": 0,
      "isConsumable": false,
      "tags": ["weapon", "melee"]
    },
    {
      "id": 2,
      "name": "Oak Shield",
      "description": "Wooden defense",
      "price": 100.0,
      "damage": 0,
      "defense": 15,
      "isConsumable": false,
      "tags": ["armor", "shield"]
    }
  ]
}

Несколько листов в одной таблице

В одной таблице можно создать несколько типов конфигов:

Лист: Items

FieldName	FieldType	...
id	int	...
name	string	...

Лист: Enemies

FieldName	FieldType	...
id	int	...
name	string	...
health	int	...

C4G сгенерирует:

• Items.cs и JSON Items
• Enemies.cs и JSON Enemies
• RootConfig.cs (содержит оба конфига)

Рекомендации

Соглашения об именовании

✅ ДЕЛАЙТЕ:

• Используйте PascalCase для названий листов: Items, EnemyStats
• Используйте camelCase для имён полей: id, itemName, maxHealth
• Используйте описательные имена: attackDamage, а не dmg

❌ НЕ ДЕЛАЙТЕ:

• Избегайте пробелов в названиях листов: Enemy Stats → EnemyStats
• Избегайте специальных символов: item-name → itemName
• Избегайте зарезервированных ключевых слов C#: class, int, string в качестве имён полей

Организация данных

✅ ДЕЛАЙТЕ:

• Держите связанные данные на одном листе
• Используйте единообразный порядок столбцов
• Добавляйте уникальное поле id в каждый конфиг
• Группируйте похожие элементы вместе

❌ НЕ ДЕЛАЙТЕ:

• Не смешивайте несвязанные типы данных на одном листе
• Не оставляйте пустые строки между данными
• Не используйте объединённые ячейки
• Не добавляйте комментарии или заметки в ячейки с данными

Советы по производительности

• Ограничьте количество столбцов: Google Sheets API работает быстрее с менее чем 100 столбцами на лист
• Кэшируйте сгенерированные файлы: Добавляйте сгенерированный JSON в систему контроля версий для использования во время выполнения
• Разделяйте листы: Используйте несколько листов для разных типов конфигов
• Избегайте сложных формул: C4G читает исходные значения, а не результаты формул

Разрешения для таблицы

Для личных проектов

1. Держите таблицу приватной (без общего доступа)
2. Доступ через OAuth личного аккаунта Google

Для командных проектов

1. Предоставьте доступ к таблице членам команды:

   • Нажмите «Поделиться» в Google Sheets
   • Добавьте членов команды с доступом «Редактор»

2. Каждому члену команды нужны собственные OAuth-учётные данные

3. Рассмотрите использование Google Workspace для лучшего управления командой

Типовые структуры листов

RPG-предметы

FieldName	FieldType	Описание
id	int	Уникальный идентификатор
name	string	Отображаемое имя
description	string	Текст подсказки
iconId	string	Ссылка на спрайт иконки
rarity	ItemRarity	Enum: Common, Rare и т.д.
stackSize	int	Макс. стопка в инвентаре
sellPrice	int	Стоимость у торговца

Характеристики персонажа

FieldName	FieldType	Описание
characterId	int	Уникальный ID
displayName	string	Имя персонажа
baseHealth	int	Начальное HP
baseAttack	int	Начальная атака
baseDefense	int	Начальная защита
movementSpeed	float	Скорость передвижения (ед/сек)
specialAbilities	string[]	Список ID способностей

Дизайн уровней

FieldName	FieldType	Описание
levelId	int	Уникальный идентификатор
sceneName	string	Сцена Unity для загрузки
displayName	string	Название уровня в UI
difficulty	int	Сложность от 1 до 10
requiredLevel	int	Требуемый уровень игрока
enemySpawns	string[]	ID врагов для появления
rewardCoins	int	Награда за прохождение

Устранение неполадок

Ошибка «Sheet not found»

Причина: Название листа не совпадает с настройками C4G

Решение:

• Проверьте точное название листа (с учётом регистра)
• Уберите пробелы и специальные символы
• Убедитесь, что лист существует в таблице

Ошибка «Invalid spreadsheet ID»

Причина: Неверно скопированный ID из URL

Решение:

• Скопируйте ID между /d/ и /edit в URL
• Убедитесь, что нет лишних пробелов или символов
• Проверьте, открыв URL в браузере

Ошибка «Type not supported»

Причина: Используется тип, который C4G не распознаёт

Решение:

• Проверьте список поддерживаемых типов выше
• Зарегистрируйте пользовательские перечисления в настройках C4G
• Создайте парсер пользовательского типа (продвинутый уровень)

«Данные парсятся неверно»

Причина: Формат данных не соответствует ожидаемому типу

Решение:

• Проверьте формат данных (например, true/false для bool, не yes/no)
• Проверьте наличие лишних пробелов в ячейках
• Убедитесь, что списки используют запятые без пробелов в качестве разделителей

Пустые или null-значения

Причина: Отсутствие данных в таблице

Решение:

• C4G обрабатывает пустые ячейки как значения по умолчанию:
  • int: 0
  • float/double: 0.0
  • bool: false
  • string: пустая строка ""
  • Списки: пустой массив []

Следующие шаги

• Рабочий процесс в редакторе — Генерация конфигов в Unity
• Справочник API — Подробнее об API C4G
• Парсеры пользовательских типов — Расширение C4G с пользовательскими типами