ANI-EGG • Přednáška #2

Pravidla pro větší projekty

Koncepty VCS, struktura složek, naming conventions, presety, code style a best practices pro týmovou práci.

Petr Pauš
FIT ČVUT v Praze
Úvod • Osnova

Obsah

Úvod a koncepty

  • 1. Úvod: proč jsou potřeba pravidla.
  • 2. Source control vs. version control: terminologie.
  • 3. Základní koncepty.

Organizace projektu

  • 4. Best practices pro organizaci: struktura složek, prázdné složky, .meta, naming standardy, Presety, standardy kódu.

Nástroje a nastavení

  • 5. Systémy správy verzí: Git, Perforce Helix Core, SVN, Plastic SCM.
  • 6. Nastavení Unity: Version Control settings, co ignorovat, velké soubory.

Praxe

  • 7. Best practices pro správu verzí: commity, denní workflow, větve, pull requesty.
  • 8. Shrnutí.
Úvod • Motivace

Práce ve více lidech

Co je třeba řešit

  • Kde projekt uložit, aby k němu měli přístup všichni členové týmu?
  • Co se stane, když na stejném souboru pracuje více lidí současně?
  • Programátoři chápou koncepty správy kódu: ale co umělci a netechničtí členové týmu?
  • Jak minimalizovat potřebu podpory ze strany programátorů, aby se ostatní nemuseli obávat, že něco pokazí?

Správa verzí může být pro tvůrce her odrazujícím tématem, zejména bez technického zázemí. Nemusí tomu tak ale být: existuje řada nástrojů, které se přímo integrují do enginu.

„Většina problémů v týmovém vývoji není technických: je to o nedostatečné komunikaci a chybějících dohodnutých pravidlech.“

Kapitola 2 • Terminologie

Source control vs. version control

Období Charakteristika Termín
Počátky výpočetní techniky Veškerý vývoj byl „čistý kód“: dokonce i 3D grafika se popisovala kódem. Source control
nástroje jako SCM
Moderní herní vývoj Práce s FBX modely, texturami, materiály, audio soubory… VCS

Termín source control přestal pokrývat potřeby moderního vývoje: nástroje musí zvládat více než jen změny textových souborů. Proto se prosadilo označení version control system.

Plastic SCM se v roce 2020 připojil k Unity: tyto nástroje jsou proto těsně integrovány přímo do Unity Editoru.

Tři systémy, které fungují nejlépe

  • Plastic SCM (Unity)
  • Git (Unity, Godot)
  • Perforce Helix Core (Unity, Unreal, Godot)
  • Termíny source control a version control se stále používají zaměnitelně.
  • Pro game engine projekty, které pracují s velkými binárními assety, jsou ale výrazy version control a VCS přesnější.
Koncepty • Centralizované vs. distribuované

Centralizované verzování

Charakteristika

  • Kde sídlí repo: mnoho firem volí centralizovanou variantu, aby udržely servery s proprietárním softwarem na vlastní půdě. Nemusí to ale znamenat on-site servery: repo může být i v cloudu (i když méně běžně).
  • Nasazení změn: vnímáno jako přímočařejší. Změny se načítají z repozitáře a odesílají přímo do něj: updating from a committing to repo.
  • Nevýhoda: uživatelé musí být připojeni k serveru, aby mohli odeslat jakoukoli práci.
  • Řešení konfliktů: soubory lze zamknout pro modifikaci (checking out), což zabrání ostatním commitovat, dokud není soubor checked back in.

Klíčová vlastnost: uživatel má na svém workstationu vždy jen nejnovější verzi projektových souborů, zatímco server drží celou historii projektu.

Schéma centralizovaného workflow: uživatelé komunikují přímo se centrálním serverem
Centralizovaný workflow: jeden server,
uživatelé vždy s nejnovější verzí
Koncepty • Centralizované vs. distribuované

Distribuované verzování

Schéma distribuovaného workflow: každý uživatel má lokálně celou historii projektu
Distribuovaný workflow: každý má lokálně
celou historii, sdílí se push/pull

Charakteristika

  • Kde sídlí repo: stále existuje jedno místo (obvykle cloud jako GitHub), ale uživatelé naklonují celou historii na svůj workstation.
  • Výhody: pracujete na vlastní lokální kopii a commitovat můžete rychle a offline. Pro sdílení je potřeba změny pushnout a pullnout.
  • Seskupování: můžete vytvořit skupinu changesetů odpovídající větší funkci a teprve pak ji pushnout týmu.
  • Zamykání: stále dostupné, ale méně běžné: merge se dá snáze řešit.

Pullnutím nejnovějších změn do lokálního projektu můžete porovnat cizí změny s vlastními ještě předtím, než své změny pushnete do repa.

Koncepty • Trade-offs

Nevýhody distribuovaného přístupu

1. Místo na disku

  • Mít celou historii na lokálních strojích zabírá hodně místa: zejména pro týmy pracující s binárními souborovými typy.
  • Git má možnost LFS, která převádí historii určitých souborů na textové pointery a odlehčuje repozitář.
  • Jiné soubory ale mají celou historii: repozitáře mohou skončit s hromadou starých či nepotřebných testovacích dat.
  • Firmy s menšími disky mohou narazit na velikost repa se starými verzemi a přetíží disky.

2. Izolace

  • Vývojáři nemusí být v kontaktu s centrálním serverem → mohou skončit prací v izolaci na dlouhé období.
  • Jejich lokální verze se může značně vzdálit od hlavního repozitáře.
  • Když přijde čas mergovat změny zpět, může to být více práce, než očekávali.

Workflow jednotlivých systémů

Git distribuovaný
Perforce centralizovaný
Plastic SCM oba
Organizace • Struktura složek

Struktura složek

Obecná doporučení

  • Dokumentujte své naming konvence a strukturu složek: styl guide nebo projektová šablona usnadní hledání.
  • Zajistěte, aby s tím všichni souhlasili.
  • Buďte konzistentní. Neodchylujte se od zvoleného stylu. Při změně pravidel proveďte přejmenování dotčených assetů najednou.
  • Nepoužívejte mezery v názvech souborů a složek: command line nástroje mají s cestami obsahujícími mezery problémy.
  • Dodržujte doporučené styly pro daný engine.
  • Oddělte testovací a sandbox oblasti. Samostatná složka pro neprodukční scény a experimentování. Podsložky s uživatelskými jmény rozdělí pracovní oblast podle členů týmu.
  • Vyhněte se nadbytečným složkám v rootu. Obsahové soubory ukládejte do Assets. Nevytvářejte další složky v rootu, pokud to není nezbytně nutné.
  • Udržujte interní assety oddělené od third-party assetů z Asset Store a pluginů: ty mají vlastní strukturu, kterou nelze měnit.

Note: úprava cizích assetů

Pokud upravujete third-party asset nebo plugin, správa verzí vám výrazně pomůže při aktualizaci: po importu nové verze projdete diff a najdete, kde byly vaše modifikace přepsány, abyste je mohli znovu implementovat.

Organizace • Struktura složek

Dvě ukázkové struktury

Příklad 1: podle typu assetu

Assets
├── Art
│   ├── Materials
│   ├── Models
│   └── Textures
├── Audio
│   ├── Music
│   └── Sound
├── Code
│   ├── Scripts   # C# scripts
│   └── Shaders   # Shader files and shader graphs
├── Docs          # Wiki, concept art, marketing
├── Level         # Game design v Unity
│   ├── Prefabs
│   ├── Scenes
│   └── UI

Příklad 2: plošší varianta

Assets
├── Art
│   ├── Materials
│   ├── Models
│   ├── Music
│   ├── Prefabs
│   ├── Sound
│   ├── Textures
│   └── UI
├── Levels
└── Src
    ├── Framework
    └── Shaders

Neexistuje pevně stanovená struktura. Oba příklady vycházejí z rozdělení podle typu assetu.

Organizace • Typy assetů

Přehled typů assetů

Animations Animované motion clips a jejich controller soubory, Timeline assety pro cinematics, rigging informace.
Audio Audio klipy i mixery používané pro blendování efektů a hudby.
Editor Skriptované nástroje pro práci s Unity Editorem, které se neobjeví v buildu.
Fonts Fonty použité ve hře.
Materials Assety popisující vlastnosti povrchového shadingu.
Meshes Modely vytvořené v externí DCC aplikaci.
Particles Částicové simulace: Particle System nebo Visual Effect Graph.
Prefabs Znovupoužitelné GameObjekty s předpřipravenými Components. Přidejte do scény a stavte.
Scripts Veškerý uživatelsky vyvinutý kód pro gameplay.
Settings Nastavení render pipeline: HDRP, URP.
Shaders Programy běžící na GPU jako součást grafické pipeline.
Scenes Malé, funkční části projektu: často odpovídají herním úrovním nebo části úrovně.
Textures Textury pro materiály a surfacing, UI overlay prvky, lightmapy pro osvětlení.
ThirdParty Assety z externího zdroje (Asset Store). Mohou mít pevnou strukturu, kterou nelze měnit.
Organizace • Naming standardy

Naming conventions: Unreal Engine

Doporučený formát názvu

Časem ověřený formát názvů souborů z Unreal Enginu je často používaný i v Unity.

[AssetTypePrefix]_[AssetName]_[Descriptor]_[OptionalVariantLetterOrNumber]
  • AssetTypePrefix: pevně daná zkratka typu assetu psaná velkými písmeny. Vždy zakončená podtržítkem.
  • AssetName: vlastní název assetu.
  • Descriptor: dodatečný kontext, k čemu asset slouží. U textur rozliší normal mapu od opacity mapy.
  • OptionalVariantLetterOrNumber: nepovinné. Jedno písmeno nebo číslo odliší varianty téhož assetu.
Unity žádný oficiální prefix standard nemá: Unreal ano

Jak název vypadá v praxi

SM_Crate Static Mesh „Crate“
T_Stone_Normal Textura kamene, normal mapa
SM_Chair_VariantA Variantní verze téže židle
BP_Door Blueprint dveří

Proč to řešit

Konvence dělá Content Browser prohledatelný: všechny textury seřadíte jedním prefixem T_. A brání kolizím názvů mezi týmy.

Organizace • Naming standardy

Unreal Engine: prefixy podle typu assetu

Materiály a meshe

HDR_ HDRI
M_ Material
MI_ Material Instance
PHYS_ Physics Asset
PM_ Physics Material
PPM_ Post Process Material
SK_ Skeletal Mesh
SM_ Static Mesh
T_ Texture
OCIO_ OCIO Profile

Blueprints a data

AC_ Actor Component
ABP_ Animation Blueprint
BI_ Blueprint Interface
BP_ Blueprint
CT_ Curve Table
DT_ Data Table
E_ Enum
F_ Structure
WBP_ Widget Blueprint

Animace a FX

FXE_ Niagara Emitter
FXS_ Niagara System
FXF_ Niagara Function
Rig_ Rig
SKEL_ Skeleton
AM_ Montages
AS_ Animation Sequence
BS_ Blend Space

Sekvence a média

NDC_ NDisplay Configuration
LS_ Level Sequence
EDIT_ Sequencer Edits
MS_ Media Source
MO_ Media Output
MP_ Media Player
MPR_ Media Profile
SNAP_ Level Snapshots
RCP_ Remote Control Preset
Organizace • Reference

Výchozí bod: šablony Unity

Seznam šablon dostupných ke stažení v Unity Hubu
Šablony dostupné ke stažení v Unity Hubu
Ukázková scéna HDRP šablony obsahuje několik asset složek
Ukázková scéna s HDRP šablonou obsahuje
několik asset složek

Stáhnete-li si z Unity Hubu některý Template nebo Starter projekt, zjistíte, že má podsložky rozdělené podle typu assetu. Nejste omezeni těmito názvy, ale měly by vám dát dobrý výchozí bod.

Organizace • Riziko

Přesuny souborů a ztráta historie

Na dobré struktuře od začátku záleží

  • Definování dobré struktury na začátku zabrání problémům se správou verzí později.
  • Přesunete-li assety z jedné složky do druhé, některé VCS to uvidí jako smazání jednoho souboru a přidání jiného: nikoli jako přesun.
  • Tím se ztratí historie původního souboru.

Plastic SCM

  • zpracuje přesuny souborů v rámci Unity a zachovává historii
  • Je ale zásadní provést přesun přímo v Unity Editoru aby se soubor .meta přesunul spolu s assetem.
Ukázka sledování přesunů souborů se zachováním historie v Plastic SCM
Sledování přesunů souborů se zachováním historie
Organizace • Automatizace

Vytvoření struktury skriptem

Jakmile se rozhodnete pro strukturu, použijte Editor skript k opětovnému využití šablony. Skript vytvoří v Assets root složku odpovídající proměnné PROJECT_NAME: tím udržíte svou práci oddělenou od third-party balíčků.

using UnityEditor;
using UnityEngine;
using System.Collections.Generic;
using System.IO;

public class CreateFolders : EditorWindow
{
    private static string projectName = "PROJECT_NAME";

    [MenuItem("Assets/Create Default Folders")]
    private static void SetUpFolders()
    {
        CreateFolders window =
            ScriptableObject.CreateInstance<CreateFolders>();
        window.position = new Rect(
            Screen.width / 2, Screen.height / 2, 400, 150);
        window.ShowPopup();
    }

    private static void CreateAllFolders()
    {
        List<string> folders = new List<string>
        {
            "Animations", "Audio", "Editor",
            "Materials", "Meshes", "Prefabs",
            "Scripts", "Scenes", "Shaders",
            "Textures", "UI"
        };

        foreach (string folder in folders)
        {
            if (!Directory.Exists("Assets/" + folder))
            {
                Directory.CreateDirectory(
                    "Assets/" + projectName + "/" + folder);
            }
        }
        List<string> uiFolders = new List<string>
        {
            "Assets", "Fonts", "Icon"
        };

        foreach (string subfolder in uiFolders)
        {
            if (!Directory.Exists(
                "Assets/" + projectName + "/UI/" + subfolder))
            {
                Directory.CreateDirectory(
                    "Assets/" + projectName + "/UI/" + subfolder);
            }
        }

        AssetDatabase.Refresh();
    }

    void OnGUI()
    {
        EditorGUILayout.LabelField(
            "Insert the Project name used as the root folder");
        projectName = EditorGUILayout.TextField(
            "Project Name: ", projectName);
        this.Repaint();

        GUILayout.Space(70);

        if (GUILayout.Button("Generate!"))
        {
            CreateAllFolders();
            this.Close();
        }
    }
}
Organizace • .meta soubory

Soubor .meta: proč ho commitovat

Klíčová pravidla

  • Režim Visible Meta Files by měl být zapnut ve Version Control window: pokud nepoužíváte vestavěné režimy Plastic SCM nebo Perforce.
  • Přestože je .meta soubor automaticky generován, drží velké množství informací o souboru, se kterým je spojen.
  • Typické u assetů s import settings: Textures, meshes, audio clips atd.
  • Změníte-li import settings, změny se zapíší do .meta souboru, nikoli do asset souboru.
  • Proto .meta soubory commitujeme do repozitáře: aby všichni pracovali se stejnými nastaveními.

Obecně platí, že automaticky generované soubory do správy verzí nepatří. .meta je výjimka: bez něj by každý člen týmu viděl jiná import nastavení.

Nastavení Visible Meta Files ve Version Control window
Zapněte Visible Meta Files při práci s Gitem
Diff souboru .meta po úpravě import settings
Změny v .meta souboru
při úpravě import settings
Organizace • Naming standardy

Standardy pojmenování

Shoda na standardech nekončí u struktury složek. Neexistuje definitivní standard pro GameObjekty: zvažte ale následující:

Standard Příklad Vysvětlení
Popisné názvy, nezkracovat largeButton, LargeButton, leftButton
NE: lButton
Názvy, které si pamatujete i za několik měsíců. Zkratky a pravopisné chyby vytvářejí zmatek.
camelCase / PascalCase OutOfMemoryException, dateTimeFormat
NE: Outofmemoryexception
Vyhněte se mezerám. Zlepšuje čitelnost i přesnost psaní.
Podtržítka a pomlčky střídmě Active States: EnterButton_Active, EnterButton_Inactive
Texture Maps: Foliage_Diffuse, Foliage_Normalmap
LOD: Building_LOD1, Building_LOD0
Prefix s podtržítkem řadí abecedně na první místo. Podtržítka označují varianty objektu.
Číselné suffixy pro sekvence Node0, Node1, Node2… Nepřidávejte číslo, pokud není součástí seznamu.
Dodržujte design dokument HighSpellTower, RedDragonLair Pokud design dokument lokaci pojmenovává, použijte přesně tento pravopis.
Organizace • Optimalizace

Rozdělte assety

Velké scény se nehodí pro spolupráci

  • Rozdělte úrovně do mnoha menších scén, aby umělci a designéři mohli lépe spolupracovat na jedné úrovni a zároveň minimalizovali riziko konfliktů.
  • V runtime může projekt načítat scény aditivně: SceneManager.LoadSceneAsync s parametrem LoadSceneMode.Additive.
  • Rozdělte práci do Prefabů, kde je to možné. Změnu pak provedete v Prefabu, ne ve scéně: a vyhnete se konfliktu s kýmkoli, kdo pracuje na scéně.
  • Změny v Prefabech jsou navíc často čitější při diffu.

Unity SmartMerge

Pokud přesto skončíte s konfliktem ve scéně, Unity má vestavěný YAML nástroj speciálně pro mergování scén a Prefabů.

// Aditivní načítání scén za běhu
SceneManager.LoadSceneAsync(
    "LevelPart02",
    LoadSceneMode.Additive
);

Více viz Smart Merge v dokumentaci Unity.

Organizace • Presety

Presety

Co to je

Umožňuje přizpůsobit výchozí stav čehokoli v Inspectoru. Můžete zkopírovat nastavení komponenty nebo assetu, uložit je jako asset a později stejné nastavení použít na jiný objekt.

  • Používejte Presety k vynucení standardů nebo k aplikaci rozumných výchozích hodnot na nové assety.
  • Zajistíte tak konzistentní standardy napříč týmem, takže běžně přehlížená nastavení neovlivní výkon projektu.

Postup

  1. Klikněte na ikonu Presetu v pravém horním rohu komponenty.
  2. Klikněte na Save current to… pro uložení Presetu jako assetu.
  3. Klikněte na jeden z dostupných Presetů pro načtení sady hodnot.
Ikona Presetu zvýrazněná červeně v pravém horním rohu komponenty
Ikona Presetu je zvýrazněna červeně
Presety obsahující různá Import Settings pro 2D textury podle použití
Presety s různými Import Settings pro 2D textury
(albedo, normal, utility)
Organizace • Presety

Presety: další možnosti

Vytvoření GameObjektu s výchozími hodnotami

Přetáhněte Preset asset do Hierarchy a vytvořte nový GameObject s odpovídající komponentou obsahující hodnoty z Presetu.

Přiřazení typu v Preset Manageru

V Project Settings > Preset Manager určete jeden nebo více Presetů na typ. Vytvoření nové komponenty pak bude defaultně používat zadané hodnoty.

Tip: Vytvořte více Presetů na typ a spoléhejte na filtr podle názvu.

Uložení nastavení manageru

Presety fungují i pro okna Manager: například tags a layers nebo physics nastavení. Zkrátí čas při rozjezdu dalšího projektu.

Preset Manager s nastavením Presetů pro 2D textury
Preset Manager: nastavení Presetů pro 2D textury
Organizace • Standardy kódu

Standardy kódu a namespaces

Namespaces

  • Pomáhají lépe organizovat kód a oddělit moduly uvnitř projektu.
  • Vyhnete se konfliktům s third-party assety, kde se názvy tříd mohou opakovat.
  • Při používání namespaces rozdělte strukturu složek podle namespace pro lepší organizaci.

Standardní hlavička

  • Hlavička v šabloně kódu dokumentuje účel třídy, datum vytvoření, autora.
  • Mohlo by se to ztratit v historii projektu snadno ztratí : i při použití správy verzí.

Kde žijí šablony skriptů

Unity použije šablonu z %EDITOR_PATH%\Data\Resources\ScriptTemplates při každém vytvoření nového skriptu nebo shaderu:

  • Windows:
    C:\Program Files\Unity\Editor\Data\Resources\ScriptTemplates
  • Mac:
    /Applications/Hub/Editor/[version]/Unity/Unity.app/Contents/Resources/ScriptTemplates

Projektově specifické šablony

Vytvořte složku Assets/ScriptTemplates a zkopírujte šablony do ní: přepíšete tím výchozí hodnoty. Můžete upravit i globální šablony, ale před změnou si zálohujte originály. Každá verze Unity má vlastní složku šablon.

Organizace • Šablony

Výchozí šablona MonoBehaviour

Soubor 81-C# Script-NewBehaviourScript.cs.txt. Existují také šablony pro shadery, další behavior skripty a assembly definitions.

using System.Collections;
using System.Collections.Generic;
using UnityEngine;

#ROOTNAMESPACEBEGIN#
public class #SCRIPTNAME# : MonoBehaviour
{
    // Start is called before the first frame update
    void Start()
    {
        #NOTRIM#
    }

    // Update is called once per frame
    void Update()
    {
        #NOTRIM#
    }
}
#ROOTNAMESPACEEND#

Dvě užitečná klíčová slova

  • #SCRIPTNAME#: označuje zadaný název souboru nebo výchozí název (například NewBehaviourScript).
  • #NOTRIM#: zajišťuje, že závorky obsahují řádek bílého prostoru.

Vlastní klíčová slova

Můžete použít vlastní klíčová slova a nahradit je Editor skriptem implementujícím metodu OnWillCreateAsset.

Jakmile se rozhodnete pro standardy kódu, držte se jich: žádná pevně daná pravidla neexistují, důležitá je konzistence týmu.

Organizace • Automatizace

Automatická hlavička skriptu

Použijte hlavičku ze skriptu níže uvnitř šablony skriptu a každý nový skript bude vytvořen s hlavičkou zobrazující datum, autora a projekt. Užitečné, pokud kód v budoucnu znovu použijete jinde.

Unity zavolá OnWillCreateAsset před vytvořením každého assetu: skript tak může obsah souboru ještě upravit.

// /*-------------------------------------------
// ---------------------------------------------
// Creation Date: #DATETIME#
// Author: #DEVELOPER#
// Description: #PROJECTNAME#
// ---------------------------------------------
// -------------------------------------------*/

using UnityEngine;
using UnityEditor;

public class KeywordReplace
    : UnityEditor.AssetModificationProcessor
{
    public static void OnWillCreateAsset(string path)
    {
        path = path.Replace(".meta", "");
        int index = path.LastIndexOf(".");
        if (index < 0) return;

        string file = path.Substring(index);
        if (file != ".cs" && file != ".js"
            && file != ".boo") return;
        index = Application.dataPath.LastIndexOf("Assets");
        path = Application.dataPath.Substring(0, index)
               + path;
        if (!System.IO.File.Exists(path)) return;

        string fileContent =
            System.IO.File.ReadAllText(path);

        fileContent = fileContent.Replace(
            "#CREATIONDATE#",
            System.DateTime.Today
                .ToString("dd/MM/yy") + "");
        fileContent = fileContent.Replace(
            "#PROJECTNAME#",
            PlayerSettings.productName);
        fileContent = fileContent.Replace(
            "#DEVELOPER#",
            System.Environment.UserName);

        System.IO.File.WriteAllText(path, fileContent);
        AssetDatabase.Refresh();
    }
}
Kód • Casing

Terminologie zápisu (casing)

Než se pustíme do pravidel, sjednoťme si názvosloví: v týmu se bez něj nedomluvíte.

Zápis Příklad Kde se používá
camelCase currentHealth Slova oddělená jedním velkým písmenem, první písmeno malé. Lokální proměnné a parametry metod.
PascalCase CurrentHealth Varianta camel case s velkým počátečním písmenem. V Unity pro třídy, veřejná pole a názvy metod.
snake_case current_health Mezery mezi slovy nahrazeny podtržítkem.
kebab-case current-health Mezery nahrazeny pomlčkami. Běžné ve webových technologiích, zejména CSS: a doporučuje se i pro UI Toolkit USS.
Hungarian notation fHealth Název nese typ nebo záměr proměnné. Je to starší konvence a v Unity vývoji není běžná.

Kebab-case na dvou místech: v C# ho jako identifikátor použít nemůžete (pomlčka je operátor mínus), ale v CSS a USS je standardem. Počítejte s tím, když pojmenováváte elementy v UI Toolkit.

Unity • Proměnné

Unity: Proměnné

Používejte podstatná jména

Názvy proměnných by měly být popisné, jasné a jednoznačné: reprezentují věc nebo stav.

Boolean začněte slovesem

Tyto proměnné nesou hodnotu true/false. Předpona slovesem vyjasní význam.

isDead, isWalking, hasDamageMultiplier

Smysluplné názvy, nezkracovat

Název má prozradit záměr, snadno se vyslovovat a hledat. Výjimkou jsou zavedené matematické zkratky.

Žádné vtipy a slovní hříčky

infiniteMonkeys nebo dudeWheresMyChar pobaví jednou: po několika desítkách čtení už ne.

Vyhněte se redundantním názvům

Když se vaše třída jmenuje Player, nepotřebujete členské proměnné PlayerScore ani PlayerTarget.

Čitelnost před stručností

CanScrollHorizontally
ScrollableX

Příklad pochází přímo z dokumentace Microsoftu.

Omezené použití var

var jen pro implicitně typované lokální proměnné: pokud to pomáhá čitelnosti a typ je zřejmý.

Jedna deklarace na řádek

Je to méně kompaktní, ale výrazně to zlepšuje čitelnost: a hlavně diffy ve správě verzí.

Kód • Proměnné

Unity: Deklarace proměnných

Pravidlo Příklad Vysvětlení
Veřejná pole PascalCase,
soukromé camelCase
DamageMultiplier
_currentHealth
Veřejná pole MyPropertyName,
soukromé proměnné myPrivateVariable.
Zvažte prefix pro soukromé členy _currentHealth Některé příručky doporučují přidat podtržítko, aby se soukromé členy odlišily od lokálních proměnných.
Konstanty s prefixem k_ k_MaxHealth Prefix k_ a PascalCase.
Odliší konstanty od běžných proměnných a vlastností.
Jednotně uvádějte modifikátory přístupu private / public Když modifikátor vynecháte, kompilátor předpokládá private.
Buďte konzistentní: buď všude, nebo nikde.
Zahazujte redundantní inicializátory int count; Žádné = 0 u číselných typů ani = null u referenčních typů.
Jedna proměnná na řádek int a;
int b;
Méně kompaktní, ale čitější.

Pole se inicializují automaticky na výchozí hodnoty: obvykle 0 u číselných typů. Explicitní = 0 je proto jen šum.

Kód • Ukázka

Unity: Příklad veřejných a soukromých proměnných

// EXAMPLE: Public and private variables

public float DamageMultiplier = 1.5f;
public float MaxHealth;
public bool IsInvincible;

private bool _isDead;
private float _currentHealth;

// parameters
public void InflictDamage(float damage, bool isSpecialDamage)
{
    // local variable
    int totalDamage = damage;

    // local variable versus public member variable
    if (isSpecialDamage)
    {
        totalDamage *= DamageMultiplier;
    }

    // local variable versus private member variable
    if (totalDamage > _currentHealth)
    {
        /// ...
    }
}

Boolean v praxi

IsInvincible a _isDead čtete jako otázku. if (_isDead) se čte samo.

Tři úrovně viditelnosti v jednom souboru

  • DamageMultiplier, MaxHealth, IsInvincible: veřejná pole, PascalCase.
  • _isDead, _currentHealth: soukromé členy, prefix podtržítkem.
  • damage, isSpecialDamage, totalDamage: parametry a lokální proměnné, camelCase.

Proč to funguje

Na řádku totalDamage *= DamageMultiplier; je na první pohled jasné, že jde o veřejné pole. Kdyby se všechno jmenovalo stejně, museli byste skákat do deklarace.

Kód • Enums

Unity: Enums

Pravidla

  • PascalCase pro název enumu i jeho hodnoty.
  • Jednotné číslo v názvu: enum reprezentuje jednu hodnotu z množiny možností.
  • Žádný prefix ani suffix.
  • Veřejné enumy můžete umístit mimo třídu, aby byly globální.
  • Bitové enumy s atributem [System.Flags] jsou výjimkou: ty se obvykle pluralizují, protože zastupují více než jeden typ.

Singular vs. plural není formalita. WeaponType zastupuje jednu zbraň. AttackModes zastupuje kombinaci více módů najednou.

// EXAMPLE: Enums use singular nouns …
public enum WeaponType
{
    Knife,
    Gun,
    RocketLauncher,
    BFG
}

// EXAMPLE: … but a bitwise enum is plural.

[Flags]
public enum AttackModes
{
   // Decimal                          // Binary
   None = 0,                          // 000000
   Melee = 1,                         // 000001
   Ranged = 2,                        // 000010
   Special = 4,                       // 000100

   MeleeAndSpecial = Melee | Special  // 000101
}
Kód • Třídy a rozhraní

Unity: Třídy a rozhraní

Třídy

  • PascalCase a podstatná jména nebo jmenné fráze: tím se názvy typů odliší od metod, které mají slovesné fráze.
  • Máte-li v souboru MonoBehaviour, název souboru se musí shodovat. V souboru mohou být další interní třídy, ale jen jedna MonoBehaviour na soubor.

Rozhraní

  • Prefix velkým písmenem I.
  • Za ním následuje přídavné jméno popisující funkcionalitu: IKillable, IDamageable.

Unity zobrazuje název skriptu v Inspectoru podle názvu souboru. Když se rozejdou, komponentu nepřidáte.

// EXAMPLE: Class formatting
public class ExampleClass : MonoBehaviour
{
    public int PublicField;
    public static int MyStaticField;

    private int _packagePrivate;
    private int _myPrivate;

    private static int _myPrivate;

    protected int _myProtected;

    public void DoSomething()
    {
    }
}

// EXAMPLE: Interfaces
public interface IKillable
{
    void Kill();
}

public interface IDamageable<T>
{
    void Damage(T damageTaken);
}
Kód • Metody

Unity: Metody

Tři pravidla

  • Začněte slovesem nebo slovesnou frází. V případě potřeby přidejte kontext.
  • Parametry v camelCase: formátujte je stejně jako lokální proměnné.
  • Metody vracející bool pokládají otázku. Stejně jako booleovské proměnné je začněte slovesem, pokud vracejí true/false.

Otázky místo konstatování

IsGameOver
HasStartedTurn
GameOver
StartedTurn
// EXAMPLE: Methods start with a verb.
public void SetInitialPosition(float x, float y, float z)
{
    transform.position = new Vector3(x, y, z);
}

// EXAMPLE: Methods ask a question
// when they return bool.
public bool IsNewPosition(Vector3 currentPosition)
{
    return (transform.position == newPosition);
}

Metoda IsNewPosition() se v podmínce čte jako věta: if (IsNewPosition(pos)). Bez Is byste hádali, co vlastně vrací.

Kód • Události

Unity: Události a jejich obsluha

Pojmenujte událost slovesnou frází

Přítomné příčestí = událost před akcí, minulé příčestí = událost po ní.

OpeningDoor
DoorOpened

Použijte System.Action

  • Ve většině případů zvládne Action<T> delegát všechny události potřebné pro gameplay.
  • Můžete předat 0 až 16 vstupních parametrů různých typů, návratový typ je void.
  • Použití předdefinovaného delegáta šetří kód.
  • Lze použít i EventHandler / EventHandler<TEventArgs>: domluvte se v týmu jednotně.

Metoda, která událost vyvolává

Subjekt událost obvykle vyvolává z metody s prefixem „On": OnOpeningDoor, OnDoorOpened.

// using System.Action delegate
public event Action OpeningDoor;   // event before
public event Action DoorOpened;    // event after

public event Action<int> PointsScored;

// raises the Event if you have subscribers
public void OnDoorOpened()
{
    DoorOpened?.Invoke();
}

public void OnPointsScored(int points)
{
    PointsScored?.Invoke(points);
}
Kód • Namespaces

Unity: Namespaces a prefixy

Pravidla

  • PascalCase bez speciálních znaků a podtržítek.
  • Přidejte using na začátek souboru: vyhnete se opakovanému psaní prefixu.
  • Tvořte pod-namespace a oddělujte úrovně tečkou: skripty tak uspořádáte do hierarchických kategorií.
  • Namespace by měl odrážet strukturu složek projektu: logicky seskupuje související třídy a usnadňuje orientaci v kódu.

Namespace = složka

Assets/_Project/Scripts/Enemy/ → namespace Enemy. Když se struktura složek a namespace rozejdou, nový člen týmu hledá zbytečně dlouho.

namespace Enemy
{
    public class Controller1 : MonoBehaviour
    {
        ...
    }

    public class Controller2 : MonoBehaviour
    {
        ...
    }
}

Prefixy pro atributy

Někdy se používají prefixy pro soukromé atributy (m_), konstanty (k_) nebo statické proměnné (s_).

Kód • Godot

Godot: GDScript style guide

Psaní kódu v Godotu

  • GDScript je dynamický jazyk.
  • Nemá kompilátor, který by vynutil typy a zachytil chyby.
  • Konvence tady nahrazuje část kontroly, kterou v C# nebo C++ dělá překladač.
  • Godot dokáže typy proměnných vynucovat (při parsování).
  • Lze proměnné anotovat typem (název : typ), čímž pak vznikají safe lines.
  • Lze nastavit, aby godot hlásil neanotovanou proměnnou jako warning, nebo dokonce jako error.
  • Kroky při zpracování:
    • Tokenizace a Parsování: sestavení AST.
    • Bytecode Compilation: sestavení byte-code.
    • Virtual Machine Interpretation: Interpretace byte-code.

Pár zajímavostí

  • Taby, ne mezery. Přesně opačně, než velí konvence C#.
  • snake_case pro funkce a proměnné: ne camelCase jako v C#.
  • Underscore znamená soukromé: stejná myšlenka jako v Unity, ale aplikovaná důsledně včetně metod.

Ponaučení:

Konvence se mezi enginy liší, ale princip je stejný: vyberte pravidla, zapište je a držte se jich. Špatná konvence dodržovaná je lepší než pět dobrých.

Kód • Godot

GDScript: naming conventions

Co Zápis Příklad a pravidlo
Soubory snake_case class_name Weapon → soubor weapon.gd;
class_name YAMLParser → yaml_parser.gd.
PascalCase názvu třídy se převádí na snake_case.
Třídy a uzly PascalCase CharacterBody3D: stejně jako v C#.
Funkce a proměnné snake_case var particle_effect,
func load_level():
Soukromé a virtuální _snake_case Podtržítko na začátku:
var _counter = 0,
func _recalculate_path():.
Platí i pro virtuální metody, které uživatel musí přepsat.
Signály snake_case, minulý čas signal door_opened,
signal score_changed
Konstanty CONSTANT_CASE Vše velkými písmeny s podtržítkem: const MAX_SPEED = 200
Enumy název PascalCase, položky CONSTANT_CASE Název v jednotném čísle (reprezentuje typ), položky jako konstanty.
Načtení třídy PascalCase const Weapon = preload("res://weapon.gd"):
i konstanta s třídou má PascalCase, ne CONSTANT_CASE.
Kód • Godot

GDScript: formátování 1/2

Odsazení

  • Taby místo mezer: výchozí nastavení editoru.
  • Každá úroveň odsazení je o jednu větší než blok, který ji obsahuje.
  • 2 úrovně odsazení odliší pokračovací řádky od běžných bloků. Výjimka: pole, slovníky a enumy používají jednu úroveň.

Délka řádku

Pod 100 znaků povinně. Pokud můžete, držte se pod 80.

Jeden příkaz na řádek

Nevkládejte víc příkazů na jeden řádek, ani podmínky. Jediná výjimka je ternární operátor.

Trailing comma

Čárka na posledním řádku u polí, slovníků a enumů. U jednořádkových seznamů ne: tam je zbytečná.

# Trailing comma - správně
var array = [
    1,
    2,
    3,
]

# Pokračovací řádek - 2 úrovně odsazení
if (foo and bar) \
        or not baz:
    print("condition is true")
Kód • Godot

GDScript: formátování 2/2

Booleovské operátory

  • Preferujte and, or, not před &&, ||, !: jsou přístupnější.
  • Při zalamování patří and/or na začátek pokračovacího řádku, ne na konec předchozího.
# Bílé znaky
position.x = 5
my_array = [4, 5, 6]
my_dictionary = { key = "value" }
print("foo")

# Čísla
var hex_number = 0xfb8c0b
var large_number = 1_234_567_890

Enumy po jednom prvku na řádek

Godot to zdůvodňuje dvěma věcmi: snáz se nad každý prvek píše dokumentační komentář a vznikají čistší diffy, když prvek přidáte nebo odeberete.

enum Element {
    EARTH,
    WATER,
    AIR,
    FIRE,
}

Název enumu je v jednotném čísle: Element zastupuje jeden prvek ze čtyř. Stejná logika jako WeaponType v Unity.

Mezery kolem =, mezera po čárce, žádná mezera mezi jménem funkce a závorkou. Dlouhá čísla oddělujte podtržítkem.

Kód • Godot

GDScript: signály

class_name StateMachine
extends Node
## Hierarchical State machine for the player.

signal state_changed(previous, new)

@export var initial_state: Node
@onready var _state = initial_state

func _ready():
    state_changed.connect(_on_state_changed)
    _state.enter()

func transition_to(target_state_path, msg={}):
    _state.exit()
    self._state = target_state
    _state.enter(msg)
    state_changed.emit()

func _on_state_changed(previous, new):
    print("state changed")

Signály místo událostí

  • Deklarují se klíčovým slovem signal,
    název v minulém čase.
  • Připojují se v _ready() voláním signal_name.connect(_callback).
  • Vyvolávají se metodou .emit(): obdoba Invoke() v C#.
  • Obslužná metoda má prefix _on_ a je soukromá (podtržítko).
Kód • Godot

GDScript: pořadí kódu v souboru

Godot jako jediný z těchto tří enginů doporučuje i pořadí, v jakém mají být části souboru.
Díky tomu vývojář ví, kam sáhnout, aniž by musel číst.

Hlavička a metadata (1–4)

  1. @tool, @icon, @static_unload
  2. class_name
  3. extends
  4. ## dokumentační komentář

Data a stav (5–11)

  1. signals
  2. enums
  3. constants
  4. statické proměnné
  5. @export proměnné
  6. ostatní běžné proměnné
  7. @onready proměnné

Metody (12–17)

  1. _static_init()
  2. ostatní statické metody
  3. přepsané virtuální metody: _init(), _enter_tree(), _ready(), _process(), _physics_process()…
  4. přepsané vlastní metody
  5. ostatní metody
  6. vnořené třídy

Navíc platí: veřejné před soukromým · vlastnosti a signály před metodami · virtuální callbacky před rozhraním třídy · konstrukce a inicializace (_init, _ready) před metodami, které objekt mění za běhu.

Kód • Srovnání

Unity (C#) vs. Godot (GDScript)

Prvek Unity: C# Godot: GDScript
Třída PascalCase: PlayerController PascalCase: PlayerController
Soubor Musí odpovídat třídě: PlayerController.cs snake_case: player_controller.gd
Metoda PascalCase: ApplyDamage() snake_case: apply_damage()
Veřejná proměnná PascalCase: MaxHealth snake_case: max_health
Soukromá proměnná _camelCase: _currentHealth _snake_case: _current_health
Konstanta k_PascalCase: k_MaxHealth CONSTANT_CASE: MAX_HEALTH
Událost / signál Minulé příčestí: DoorOpened Minulý čas: door_opened
Enum: položky PascalCase: Melee CONSTANT_CASE: EARTH
Odsazení Čtyři mezery Taby

Co mají společné: třídy v PascalCase, podtržítko pro soukromé členy, události v minulém čase, enumy v jednotném čísle. Kde se liší: metody a proměnné (PascalCase vs. snake_case), konstanty a odsazení.

Nastavení • Co ignorovat

Co ignorovat

Pravidlo

  • Pod správu verzí by měly být umístěny pouze soubory, které nelze generovat.
  • Pro Unity to znamená commitnout pouze soubory ve složkách Assets a Project Settings. Unity dokáže automaticky znovu vytvořit všechny ostatní složky.

Za žádných okolností necommitujte složku Library

Tato složka může být velmi velká a Unity ji při spuštění Editoru znovu vytvoří, pokud neexistuje.

Konkrétní systémy

  • Perforce: musíte explicitně přidat složky Assets a Project Settings do svého depotu.
  • Plastic SCM: automaticky vybírá vhodné složky a soubory. Seznam je uložen v souboru ignore.conf v rootu projektu.
  • Git: vyžaduje .gitignore, který indikuje, které soubory nikdy nezahrnout. Šablonu lze vybrat při vytváření repozitáře nebo přes GitHub.

Dále se vyhněte commitování

.exe .apk gradle projekty xcode projekty

Výjimka: při automatizovaných build procesech je commitněte do vlastního repozitáře.

Nastavení • Velké soubory

Práce s velkými soubory

Binární soubory: dva důsledky

  • Projekty v Unity nebo Godotu se skládají z mnoha netextových souborů.
  • Skripty mohou být často v menším počtu než jiné asset soubory: textury, modely, Prefaby, audio.
  • Je obtížné je porovnávat mezi revizemi.
  • Diff nelze popsat, takže celý soubor je zapsán, když je změna pushnuta do repa.

V distribuovaném prostředí máte celou historii lokálně. U velkých souborů s mnoha změnami tak máte tolik kopií souboru na svém stroji: což rychle spotřebuje místo na disku.

Systém Přístup k velkým souborům
Perforce Centralizovaný systém, který dobře zvládá velké soubory.
Plastic SCM Zvládá velké soubory centralizovaně, ale dává i možnost distribuované pipeline. Velikost souborů je tradeoff.
Git Jako distribuovaný systém může mít problémy. Použijte Git LFS: nahrazuje velké soubory v .git textovými pointery, skutečný asset ukládá na server.

Plastic SCM Dynamic Workspace

Spoléhá na virtuální filesystem: stahuje soubory on demand. Ve workspace vidíte vše, ale ve skutečnosti není vše staženo.

Shrnutí

Co si odnést

1. Správa verzí není volitelná

I malý tým potřebuje historii. Bez ní přicházíte o možnost vrátit se a zjistit, co se pokazilo.

2. Centralizované vs. distribuované

Distributed je flexibilnější a offline-friendly, ale sdílení změn je explicitní: musíte pushnout a pullnout.

3. Struktura od prvního dne

Složky, namespace a naming conventions se velmi špatně mění dodatečně: ztratíte historii.

4. Unity je specifické

.meta soubory, YAML assety, binární velké soubory. Nastavte Visible Meta Files a Force Text, používejte Git LFS.

5. Commitujte po malých kouscích

Jeden commit = jeden úkol, se smysluplnou zprávou, bez commit -a. Nejčastější chyba začátečníků.

6. Větve a code review

U delších projektů opusťte jednu větev. Feature branches, task branches, streams: a  pull requesty jako kontrola kvality.

Unity doporučuje na konci svého best-practices průvodce jednu věc nad všechny ostatní: ujistěte se, že spolu váš tým jasně komunikuje o tom, jak bude správa verzí používána. Všechny nástroje a konvence světa nepomohou, pokud si lidé neřeknou, kdo na čem pracuje.