Skip to content

PROJECT_STRUCTURE.md

Latest commit

 

History

History
313 lines (230 loc) · 11.5 KB

PROJECT_STRUCTURE.md

File metadata and controls

313 lines (230 loc) · 11.5 KB

Cognitio - Unity AI Framework Project Structure

Projekttyp

Cognitio: A trait-based decision framework for personality-driven agents 5-Tier Product Model | 3 Base Characters from Novel

Organisationsprinzip

Hybrid-Ansatz: Kombiniert Asset-Typen mit Workflow-Phasen, optimiert für Unity-Entwicklung und gestaffeltes Asset Store Release.

📁 Hauptordner-Übersicht

01_Documentation/

Alle projektbezogenen Dokumente, Charakterprofile und Planungsunterlagen.

Concepts/

  • Character_Profiles/ - Detaillierte Profile der 3 Base-Charaktere (aus Roman)
  • Trait_System/ - Trait-Katalog, Definitionen, Kategorisierungen
  • Tier_Design/ - Feature-Matrix, Tier-Differenzierung, Upgrade-Pfade

Scripts/

  • Character_Backstories/ - Narrative Hintergründe der Base-Charaktere (spoiler-frei)

Storyboards/

  • Demo-Szenarien Visualisierungen
  • Workflow-Diagramme (User Journey pro Tier)

Technical/

  • TDD_Cognitio_v.0.2.txt - Technical Design Document (vollständig)
  • API_Design/ - API-Spezifikationen, Code-Interfaces
  • Performance/ - Performance-Benchmarks, Optimierungsstrategien

Project_Planning/

  • Roadmap/ - 5-Phasen Entwicklungsplan (PoC → Ecosystem)
  • Milestones/ - Sprint-Pläne, KPIs, Success-Kriterien

02_Assets/

Unity-Assets, wiederverwendbare Ressourcen, Core-System-Komponenten.

Characters/

Herzstück des Projekts - Alles rund um das Charakter-System

  • Base_Profiles/ - Die 3 vollständig konfigurierten Charaktere

    • Character_01_Rationaler_Stratege/ - Hohe Rationalität, niedrige Impulsivität
    • Character_02_Emotionaler_Beschuetzer/ - Hohe Empathie, hohe Loyalität
    • Character_03_Pragmatischer_Opportunist/ - Hoher Egoismus, hohe Kreativität

  • Trait_Definitions/ - 20-30 Core-Traits (ScriptableObjects)

  • Motivation_Templates/ - Vordefinierte Motivations-Sets

  • Interaction_Matrices/ - Matrix-Konfigurationen (Tier-abhängig)

Demos/

  • Scenarios/ - 3-25 Demo-Szenarien (Tier-abhängig)
  • Test_Scenes/ - Unity-Szenen für Testing und Demonstration

Scripts/

  • Core/ - Haupt-Logik (Trait System, Evaluation, Decision Engine)
  • Editor/ - Custom Inspector, Debug-Tools, Visual Node-Editor (Tier 5)
  • Utilities/ - Helper-Klassen, Extensions

Prefabs/

  • Characters/ - Vorkonfigurierte Character-Prefabs
  • UI/ - Debug-UI, Decision-Visualizer

ScriptableObjects/

  • Tiers/ - Tier-Konfigurationen (Feature-Locks, Performance-Limits)

Editor_Tools/

  • Batch-Testing Tools
  • Heatmap-Generator
  • Character-Kloning-System (Tier 3+)

03_Pre-Production/

Vorbereitungsphase - Charakter-Design, System-Prototyping.

  • Research/ - BDI-Agents, Appraisal Theory, Personality Models
  • Mockups/ - UI-Designs (Inspector, Node-Editor), Workflow-Mockups
  • Prototypes/ - Proof-of-Concept (Phase 1), Simple Interaction Matrix
  • Planning/ - Sprint-Pläne für Phase 2-5

04_Production/

Aktive Entwicklungsphase - Unity-Projekt und Feature-Implementierung.

Unity_Project/

  • Haupt-Unity-Projekt (wird hierhin referenziert oder liegt hier)

Character_Development/

  • Work-in-Progress Charakter-Konfigurationen
  • Trait-Value-Tuning
  • Behavior-Testing-Logs

Tier_Features/

Separate Entwicklung pro Tier zur Modularität

  • Tier_1_Starter/ - Basic Integration, 3 Base-Characters, Read-Only Matrix
  • Tier_2_Standard/ - Trait-Prioritäten, Extended Demos, Relationship-Values
  • Tier_3_Advanced/ - Motivation-Editor, Character-Cloning, Debug-View
  • Tier_4_Pro/ - Relationship-Rules, Context-Modifiers, Matrix-Presets
  • Tier_5_Elite/ - Full Matrix-Editor, Source Code, Custom Algorithms

Testing/

  • Unit_Tests/ - Core-Logic Tests (Trait-Evaluation, etc.)
  • Integration_Tests/ - Unity-Integration, Behavior-Controller-Tests
  • Performance_Tests/ - 20/50/100/200 NPCs Benchmarks

Raw_Files/

  • Original-Assets (Icons, UI-Grafiken vor Import)

Work_In_Progress/

  • Aktuelle Feature-Branches

Drafts/

  • Experimental Features (nicht committet)

Versions/

  • Tagged Release-Candidates

05_Post-Production/

Finalisierung, Polishing, Marketing-Material.

  • Editing/ - Video-Tutorials Schnitt, Trailer-Editing
  • VFX/ - GIF-Demos ("Same situation, 3 reactions")
  • Audio_Mix/ - Tutorial-Voiceover, Promo-Audio
  • Final_Review/ - QA vor Asset Store Submission

06_Exports/

Release-Builds, Asset Store Packages, Marketing-Material.

Asset_Store_Packages/

Separate Packages pro Tier (wichtig für gestaffelten Release)

  • Tier_1/ - Starter-Package (.unitypackage)
  • Tier_2/ - Standard-Package (Delta zu Tier 1)
  • Tier_3/ - Advanced-Package
  • Tier_4/ - Pro-Package
  • Tier_5/ - Elite-Package (mit Source Code Option)

Marketing_Materials/

  • Screenshots, GIFs, Promo-Videos
  • Asset Store Listing-Assets
  • Social-Media-Content

Documentation_PDFs/

  • User-Manual (Tier-spezifisch)
  • API-Reference
  • Tutorial-PDFs

Demo_Builds/

  • Standalone Demo-Builds (Free-Trial-Version)
  • WebGL-Demos (für Website)

03_Archive/

Langzeitspeicherung, alte Versionen, verworfene Konzepte.

  • Old_Versions/ - Alte TDD-Versionen, veraltete Charakter-Profile
  • Unused/ - Verworfene Traits, nicht verwendete Demo-Szenarien
  • Backups/ - Pre-Release Backups, Migration-Snapshots

💡 Nutzungshinweise

Cognitio Workflow (Entwicklung):

Phase 1: Proof of Concept (3 Monate)

  1. 03_Pre-Production/Prototypes/ - Minimal Trait System entwickeln
  2. 02_Assets/Characters/Base_Profiles/Character_01/ - Ersten Charakter konfigurieren
  3. 02_Assets/Demos/Scenarios/ - 1 Demo-Szenario bauen
  4. 04_Production/Testing/ - Command-Line Tests

Phase 2: Tier 1 MVP (6 Monate)

  1. 01_Documentation/Concepts/Character_Profiles/ - Alle 3 Charaktere aus Roman finalisieren
  2. 04_Production/Unity_Project/ - Unity-Integration (Prefabs, Inspector)
  3. 04_Production/Tier_Features/Tier_1_Starter/ - Tier 1 Features implementieren
  4. 06_Exports/Asset_Store_Packages/Tier_1/ - Package für Asset Store vorbereiten

Phase 3-5: Iterativ höhere Tiers entwickeln basierend auf User-Feedback

Naming Conventions (Unity-spezifisch):

Scripts: PascalCase.cs (z.B. TraitEvaluator.cs, Cognitio.cs) ScriptableObjects: SO_Description.asset (z.B. SO_Character_Rationaler_Stratege.asset) Prefabs: PFB_Description.prefab (z.B. PFB_BaseCharacter.prefab) Scenes: SCN_Description.unity (z.B. SCN_Demo_Conflict.unity)

Versionierung:

  • TDD: TDD_Cognitio_v.0.2.txt (Semantic Versioning)
  • Unity Packages: Cognitio_Tier1_v1.0.0.unitypackage
  • Releases: Tags v1.0.0, v1.1.0, etc.

Tier-Development-Strategie:

WICHTIG: Entwickle Features modular!

  • Tier 1 muss VOLLSTÄNDIG funktional sein (kein "coming soon")
  • Tier 2-5 Features werden schrittweise HINZUGEFÜGT (nicht nachträglich entwickelt)
  • Jedes Tier hat eigenen Test-Ordner in 04_Production/Testing/

Asset Store Release-Workflow:

  1. Feature in 04_Production/Tier_Features/Tier_X/ entwickeln
  2. Tests in 04_Production/Testing/ schreiben
  3. Dokumentation in 01_Documentation/ aktualisieren
  4. Package in 06_Exports/Asset_Store_Packages/Tier_X/ exportieren
  5. Marketing-Material in 06_Exports/Marketing_Materials/ vorbereiten

🎯 Projekt-spezifische Besonderheiten

3 Base-Charaktere (Kern-Asset):

  • Stammen aus Julian's Roman-Projekt
  • Liefern literarische Authentizität
  • Unterscheiden Cognitio von Konkurrenz ("AI born from storytelling")

5-Tier-System (Business-Modell):

  • Tier 1 ($19.99): Sofort nutzbar, Trait-Werte editierbar
  • Tier 2 ($49.99): Trait-Prioritäten, Relationship-Values
  • Tier 3 ($99.99): Motivation-Editor, Character-Cloning
  • Tier 4 ($199.99): Relationship-Rules, Context-Modifiers
  • Tier 5 ($499.99): Full Matrix-Editor, Source Code

Interaction Matrix (Herzstück):

  • Tier 1-2: Black Box (nicht editierbar)
  • Tier 3: Read-Only Einsicht
  • Tier 4: Presets wählbar
  • Tier 5: Visual Node-Editor (vollständige Kontrolle)

📊 Performance-Ziele (Tier-abhängig)

Tier Max NPCs @ 60fps Decision Time Memory/Char
T1-2 20-50 <2ms <3MB
T3 100 <1.5ms <5MB
T4-5 200+ <1ms <8MB

🚀 Nächste Schritte (Unmittelbar)

  1. ✅ Charakter-Auswahl: Welche 3 Charaktere aus Roman? → 01_Documentation/Concepts/Character_Profiles/
  2. Trait-Katalog: 20-30 Core-Traits definieren → 02_Assets/Characters/Trait_Definitions/
  3. Test-Szenario: Erstes Demo-Szenario designen → 02_Assets/Demos/Scenarios/
  4. Unity-Setup: Projekt-Template in 04_Production/Unity_Project/ aufsetzen

Erstellt: 2026-02-12 Angepasst für: Cognitio (Unity Framework, 5-Tier-Produkt) Version: 1.0 (TDD v0.2 aligned) Status: Produktions-bereit - Strukturiert für Phase 1 (PoC)

📚 Zusätzliche Ressourcen

Wichtige Dokumente:

  • 01_Documentation/Technical/TDD_Cognitio_v.0.2.txt - Vollständiges Technical Design Document
  • 01_Documentation/Project_Planning/Roadmap/ - 5-Phasen-Entwicklungsplan
  • 06_Exports/Marketing_Materials/ - USPs, Zielgruppen, Launch-Strategie

🔌 Cognitio → Game Engine: Integration Surface

Was ist das? CogAI produziert einen Situation Outcome (Resolved Action + Mood State). Dieses Dokument beschreibt, welche Game-Systeme diesen Output empfangen (downstream) und welche Systeme Daten in CogAI einspeisen müssen (upstream/Connectors).

Kerndokument: .planning/research/GAME_ENGINE_INTEGRATION.md

Downstream (was CogAI beeinflusst):

  • Dialogue System — Branch-Auswahl, Tonalität, freigeschaltete Optionen, per-Node-Reaktion auf Player-Choice
  • In-World Interactions — NPC-Handlungen im Spiel (Trade, Combat, Idle, Group Behavior)
  • Quest System — Outcome-Flavor, Progressions-Gates, Quest-Kategorien als CogAI-Input
  • Character Development — Relationship-Persistenz, langfristige Trait-Drift (v2+)
  • Other NPCs — Mood-Contagion, Gruppen-Dynamik, NPC-Presence als Social Modifier

Upstream Connectors (was IN CogAI fließt):

  • Scene Category Tags — Umgebungstyp, Situation-Typ, Narrative Beat
  • Player State Snapshot — Health, Reputation, Last Action, Weapon State
  • NPC Presence Context — nearby NPCs mit Mood + Relationship
  • Quest/Narrative State — aktive Quest-Kategorie, Progressions-Flags
  • Player Dialogue Choice → PlayerAction type (Hostile/Friendly/Intimidation/Deception/Neutral)

Interaction Range:

  • Definiert den gültigen Raum von CogAI-Antworten für eine Situation
  • Gefiltert durch: Scene Category + Trait-Bounds + Relationship-Thresholds + Narrative Override
  • Implementiert als InteractionRangeFilter — Pre-Pass vor WeightedSumMatrix

Phasen-Zuordnung:

Phase Integration Work
Phase 3 ContextModifier struct, SceneCategoryTag, InteractionRangeFilter stub
Phase 4 Dialogue hook, Quest hook, Player State connector, Scene tagging workflow
Phase 5 Spatial partitioning für NPC-Presence, Mood Contagion event system
Phase 6 Full authoring UI, per-node dialogue re-evaluation, debug visualization
Phase 7+ Trait drift, Cross-session persistence, full OCC player-input mapping

Cross-Media-Synergy:

  • Roman ↔ Game-Dev Feedback-Loop
  • Charaktere entwickeln sich parallel in beiden Medien
  • Langfristig: "Cognitio for Writers" (Autor-Tool)