🚀 Adastrea - Open-World Space Flight Game

March 16, 2026 · View on GitHub

Built on Unreal Engine 5.6 | MIT License | Active Development

📊 Current Status

🎯 Current Focus: Trade Simulator MVP (Week 12 of 12 - Final Polish & Demo Preparation)
🔥 Status: ACTIVE DEVELOPMENT - March 2026
🔄 Latest Update: Endless development cycle #18 - Code quality improvements and documentation updates (March 16, 2026 23:23 GMT)

🚀 Quick Navigation

👉 New to Adastrea? → docs/GETTING_STARTED.md - Start here! ⭐

For...Go to...
🎮 Want to understand the projectdocs/GETTING_STARTED.md
💻 Want to contribute codedocs/development/CONTRIBUTING.md → docs/development/CODE_STYLE.md
📚 Looking for documentationdocs/README.md or docs/DOCUMENTATION_INDEX.md
🎯 Understanding the MVPdocs/mvp/README.md
🏗️ Architecture questionsARCHITECTURE.md
📝 Recent changesdocs/CHANGELOG.md

Historical Context:

  • January 2026: Repository modernization (documentation consolidation)
  • December 2025: Critical review and MVP pivot
  • October-December 2025: Initial development (infrastructure-first approach)

Adastrea - Open World Space Flight Game

License: MIT Unreal Engine Build Status

Current Focus: Trade Simulator MVP (Dec 2025 - Mar 2026) - Building playable trading game to validate market interest

🚨 CRITICAL PROJECT UPDATE (December 29, 2025)

Project Status: TRADE SIMULATOR MVP - WEEK 1 OF 12

After comprehensive critical review (Dec 24, 2025), Adastrea is focused on a Trade Simulator MVP to validate gameplay before expanding scope.

Current Week: Week 1 (Dec 29 - Jan 4) - Hardcoded prototype foundation

Recent Progress (Dec 24-29, 2025)

  • ✅ Critical Review Complete: Identified architecture-first issues
  • ✅ Phase 2.1 Analysis: 186 functions → 64-75 MVP-critical
  • ✅ Trading Cleanup: Removed 12 non-MVP functions
  • ✅ All Roadmaps Updated: 9 documents aligned with MVP focus
  • 🔄 Week 1 In Progress: Hardcoded prototype development starting

What Happened

  • ✅ Code: 85% complete (33K lines, 22 systems)
  • ❌ Playable Content: 0% (no gameplay to test)
  • 📊 Assessment: Architecture-first approach led to over-engineering without validation

What's Changing

NEW FOCUS: Build playable trading game in 12 weeks Core Loop: Buy low → Fly → Sell high → Upgrade ship → Repeat

Scope Discipline:

  • ✅ Building: Trading system, basic flight, stations, economy
  • 🚫 Deferred: Combat, exploration, quests, crew management (until post-MVP)

Validation Gates:

  • Week 4: 60% "had fun" rating or pivot
  • Week 12: 75% "had fun", 50% "would buy" → Ready for funding

Critical Documents

Must Read Before Contributing:

  1. 📊 Critical Review Summary - Honest assessment, why we're pivoting
  2. 📋 Action Plan - 12-week recovery roadmap
  3. 🎯 MVP Instructions - What to build
  4. 🚫 Anti-Patterns - Lessons learned (18 mistakes to avoid)
  5. 📁 MVP Documentation - Current phase details

Key Principle: One polished gameplay loop beats ten half-finished systems.

🆕 Important: Documentation Reorganization (December 2025)

Major Documentation Update:

  • 📁 docs/ - All documentation now organized in structured folders
  • 📚 MASTER_DOCUMENTATION.md - Complete documentation in one comprehensive file
  • 📊 CURRENT_STATUS.md - Realistic project status (code 85% complete, content 10% complete)
  • 🗑️ Removed 80+ obsolete files - Cleaned up duplicate and outdated documentation

⚠️ Reality Check: The project is code-complete but not content-complete. C++ systems are implemented, but editor content (Blueprints, Data Assets, Maps, UI) needs to be created. See CURRENT_STATUS.md for details.

🔄 Endless Development System (March 2026)

Active Maintenance: Adastrea runs an automated endless development system with hourly cycles to maintain code quality, documentation, and GitHub activity.

Current Cycle: #18 - Code quality improvements and documentation updates (March 16, 2026 23:23 GMT)

System Overview: The Endless Development System performs hourly maintenance cycles that:

  1. Code Quality: Review TODOs, fix formatting, ensure cross-platform compatibility
  2. Documentation: Update README, CHANGELOG, and tracking documentation
  3. Testing: Run automated test suite (17+ Python tests)
  4. Health Checks: Comprehensive 7-point repository validation
  5. GitHub Activity: Regular commits demonstrating active development

Recent Improvements (Last 24 Hours):

  • ✅ Cycle #14: Trading system improvements and documentation
  • ✅ Cycle #15: Windows compatibility fixes and Unicode encoding validation
  • ✅ Cycle #16: Procedural name generators with bulk generation support
  • ✅ Cycle #17: Code quality maintenance and system documentation
  • ✅ Cycle #18: Code quality improvements and documentation updates (current)
  • ✅ Repository Health: 85.7% score with regular monitoring
  • ✅ Test Suite: 17+ Python tests passing consistently
  • ✅ Cross-Platform: Windows compatibility verified and documented

System Documentation: See Endless Development System for complete details on the automated maintenance framework.

Goal: Maintain production-ready repository with consistent quality assurance while MVP development continues.

📖 Documentation Navigation

New to Adastrea? Multiple documentation options:

Documentation Categories:

Table of Contents

About

Adastrea is an open-world space flight game built on Unreal Engine 5.6. Players can explore vast galaxies, engage in thrilling space battles, discover new planets, manage space stations, build crew relationships, and participate in a dynamic galactic economy. The project features 22 major game systems with over 33,000 lines of C++ code and comprehensive Blueprint integration.

Key Highlights

  • 🚀 Data-Driven Design: All game content uses Blueprint Data Assets
  • 🎮 Designer-Friendly: Minimal C++ knowledge required
  • 🏗️ Modular Architecture: Systems work independently and integrate seamlessly
  • 🤖 Automated Scene Population: Quickly populate levels with actors and interior layouts
  • 📚 Comprehensive Documentation: Guides, templates, and workflows for everything
  • 🔧 Blueprint First: Full Blueprint exposure for all systems

Quick Start

Prerequisites

  • Unreal Engine 5.6 (check the .uproject file for exact version)
  • Visual Studio 2022 (Windows) or Xcode (Mac) for C++ development
  • Git for version control

🆕 Build with UE Build Tools Only

You can now build Adastrea using only the Unreal Engine build tools (~500MB) instead of the full engine (~50GB):

Windows (SetEnv workaround for UE 5.6):

REM Download build tools
setup_ue_build_tools.bat

REM Build the project
build_with_ue_tools.bat Development Win64

Linux/Mac:

# Download build tools
./setup_ue_build_tools.sh

# Build the project
./build_with_ue_tools.sh Development Linux

🚨 Windows Users: If experiencing MSBuild SetEnv task failures (49KB+ include paths), this is the required workaround for UE 5.6 large projects. See Windows Build Scripts Reference.

See BUILD_WITH_UE_TOOLS.md for complete instructions.

Perfect for:

  • ✓ CI/CD pipelines
  • ✓ Automated testing
  • ✓ Build verification
  • ✓ Code compilation without full editor
  • ✓ Windows: Bypassing MSBuild SetEnv limitations

Note: To actually run and edit the project, you still need the full Unreal Engine 5.6 installation.

Robust Setup Validation

Before building the project, it's highly recommended to run our automated setup validation scripts to ensure your development environment is properly configured. These scripts check for all prerequisites, validate project structure, and can optionally perform static analysis.

Option 1: Shell Script (Linux/Mac/WSL)

# Basic validation
./Tools/SetupCheck.sh

# Validation with build folder cleanup
./Tools/SetupCheck.sh --clean

# Validation with static analysis (requires cppcheck)
./Tools/SetupCheck.sh --analyze

# Display help
./Tools/SetupCheck.sh --help

Option 2: Python Script (Cross-Platform)

# Basic validation (works on Windows, Linux, Mac)
python Tools/SetupCheck.py

# Validation with static analysis (requires cppcheck)
python Tools/SetupCheck.py --analyze

# Verbose output with detailed information
python Tools/SetupCheck.py --verbose

# Display help
python Tools/SetupCheck.py --help

The validation scripts check for:

  • ✓ Unreal Engine version compatibility (5.6)
  • ✓ C++ compiler availability (MSVC, GCC, Clang)
  • ✓ Required project folders (Source, Config, Content, Assets)
  • ✓ Required project files (.uproject, module headers)
  • ✓ Essential documentation files
  • ✓ Optional: Static code analysis with cppcheck

Note: These scripts automate many of the manual checks from Assets/PlaytestingChecklist.md. While the scripts handle environment validation, the playtesting checklist is still valuable for in-editor verification and quality assurance.

Installation

  1. Clone the repository:

    git clone https://github.com/Mittenzx/Adastrea.git
cd Adastrea

  2. Run Setup Validation (Recommended):

    # Linux/Mac/WSL
./Tools/SetupCheck.sh

# Or cross-platform Python
python Tools/SetupCheck.py

    This validates your environment and identifies any missing prerequisites before building.

  3. Generate Project Files:

  4. Build the project:

    • Open the generated .sln file in Visual Studio
    • Build in "Development Editor" configuration
    • Or open the .uproject file directly in Unreal Engine

  5. Verify Installation:

    • Launch the editor
    • Check that all example Data Assets load correctly
    • Run the game with the Play button
    • (Optional) Run AdastreaAssetValidator.py in the Unreal Editor Python console for asset validation

Testing and Automation

The project includes comprehensive automated testing tools for reliability and validation:

  • Smoke Tests: Automatically load all maps and detect missing assets, broken references, and errors
  • Screenshot Tests: Capture screenshots and perform visual regression testing against golden masters
  • Automation Runner: CLI utility for running tests and scheduling overnight validation runs
# Run all automated tests
python AutomationRunner.py --all

# Run only smoke tests
python AutomationRunner.py --smoke-test

# Schedule overnight validation at 11 PM
python AutomationRunner.py --all --schedule "23:00"

See TESTING_AUTOMATION_GUIDE.md for complete documentation.

Cloud Build Services

For automated building and CI/CD in cloud environments, multiple services are available:

  • GitHub Actions + Docker: Free for public repos, integrated CI/CD (recommended for Adastrea) ✅ Active
  • Epic Games Horde: Native UE5 build platform with distributed compilation
  • Unreal Cloud Build: Managed cloud service without self-hosting
  • TensorWorks Admiral: Enterprise-grade managed UE5 CI/CD
  • AWS Game Tech: Comprehensive cloud infrastructure for UE5

Current Status: GitHub Actions workflow is active with project validation. Docker builds require Epic Games organization membership (see detailed setup below).

Important for Docker Builds: To use Unreal Engine containers, you must:

  1. Link Epic account at www.epicgames.com/account/connections
  2. Accept Epic Games GitHub organization invitation
  3. Verify membership at github.com/EpicGames

Troubleshooting Container Access:

  • 🔍 Run diagnostics: ./test_epic_connection.sh (local) or trigger "Diagnose Container Access" workflow (GitHub Actions)
  • 📖 See CONTAINER_DIAGNOSTICS.md for comprehensive troubleshooting guide
  • ⚙️ Error: "denied"? See Container Diagnostics for specific solutions

See CLOUD_BUILD_SERVICES.md for detailed comparisons and CLOUD_BUILD_QUICK_START.md for complete setup instructions.

Procedural Content Generation

Generate randomized game content quickly with the procedural generation system:

# Generate everything at once (star systems, NPCs, quests, ships)
python ProceduralGenerators.py --type all

# Generate specific content
python ProceduralGenerators.py --type galaxy --count 10    # Star systems
python ProceduralGenerators.py --type npc --count 25       # Crew members
python ProceduralGenerators.py --type quest --count 20     # Missions
python ProceduralGenerators.py --type ship --count 8       # Ship variants

# Interactive menu
python ProceduralGenerators.py

What Gets Generated:

  • 🌌 Galaxy Systems - Complete star systems with planets, asteroids, stations, and factions
  • 👥 NPCs - Crew members with realistic names, skills, backstories, and personality traits
  • 📜 Quests - Missions with objectives, rewards, difficulty scaling, and special conditions
  • 🚀 Ship Variants - Randomized ship designs with class-appropriate stats and unique names

All generated content is saved as YAML files compatible with the existing Data Asset system and can be imported directly into Unreal Engine.

Quick Start: See PROCEDURAL_GENERATION_docs/QUICKSTART.md Full Guide: See PROCEDURAL_GENERATION_GUIDE.md

First Steps

  1. For Fast Content Creation ⭐ NEW: See FAST_FORWARD_QUICK_START.md - Generate ships, interiors, and stations in 30 minutes!
  2. For Designers: Read Assets/DesignerOnboarding.md
  3. For Programmers (C++ Focused): Read CPP_FOCUSED_SETUP.md and ESSENTIAL_BLUEPRINTS_ONLY.md
  4. For Programmers (General): Read docs/development/CONTRIBUTING.md and ARCHITECTURE.md
  5. For Playing in PIE (Quick Start): See BLUEPRINT_QUICK_START_PIE.md - Get flying in 5 minutes!
  6. For Blueprint Creation: See BLUEPRINT_REQUIREMENTS_LIST.md for complete list of required Blueprints
  7. For PIE Setup Guide: See BLUEPRINT_LIST_FOR_PIE.md for detailed blueprint checklist
  8. For Testing: Create a Test Mode level - see Docs/TestMode_INDEX.md for complete guide
  9. For Automation: See TESTING_AUTOMATION_GUIDE.md for automated testing
  10. For Procedural Content: See PROCEDURAL_GENERATION_docs/QUICKSTART.md
  11. Quick Reference: See individual system guides in the Assets/ folder

Project Roadmap

📍 Want to see where the project is headed? Check out our comprehensive ROADMAP.md for:

  • Development phases and timelines
  • Completed, in-progress, and planned features
  • Detailed feature breakdowns for all systems
  • Technical roadmap and optimization plans
  • Community and modding ecosystem plans
  • How to contribute to upcoming features

Current Status: Alpha 1.0.0-alpha - Phase 4 (Gameplay & Polish) in progress Next Milestone: Phase 4 completion and Phase 5 (Content & Beta) - 2026

📝 Contributing to the Roadmap: When submitting PRs that affect project milestones or system status, please update ROADMAP.md.

Fast-Forward Content Creation

⚡ NEW: Accelerate development with 100% FREE tools and resources!

The project is code-complete (85%) but needs content creation (10% complete). Use these guides to generate ships, interiors, station modules, and graphics in weeks instead of months:

What You Get (100% FREE)

Automated Content Generation:

  • ✅ 290+ assets in ~10 minutes (run MasterContentGenerator.py)
  • ✅ Procedural ships, NPCs, quests, stations
  • ✅ Complete VFX system generation

Free 3D Assets & Tools:

  • ✅ Quixel Megascans (10,000+ assets via Bridge - already enabled!)
  • ✅ Blender + Spaceship Generator (procedural ship creation)
  • ✅ NASA 3D Resources (real spacecraft models)
  • ✅ Sketchfab, Blend Swap, OpenGameArt (free model libraries)

Time Savings:

  • Ships: 80% faster (10 ships in 4-5 hours vs 100-200 hours)
  • Interiors: 80% faster (modular system setup once, reuse forever)
  • Station Modules: 80% faster (20 modules in 15-20 hours vs 400 hours)
  • VFX: 85% faster (24 systems in 1 hour vs 200 hours)

Total Savings: 850-950 hours (85-90% reduction)

Quick Start (30 Minutes)

# 1. Enable Python automation in Unreal Editor (5 min)
Edit → Plugins → "Python Script Plugin" → Enable → Restart

# 2. Generate all content (10 min)
Tools → Python → Python Console
>>> import MasterContentGenerator
>>> MasterContentGenerator.generate_all_content()

# 3. Access free assets (10 min)
Window → Quixel Bridge → Sign in → Download materials

# 4. Download Blender (5 min)
Visit blender.org → Download → Install

Result: Project populated with 290+ assets, ready to create custom 3D content

Resources

  • Automation Scripts: MasterContentGenerator.py, ProceduralGenerators.py, ScenePopulator.py
  • Free Asset Sources: Quixel Megascans, NASA 3D, Sketchfab, Blend Swap
  • 3D Tools: Blender (free), Spaceship Generator (free), Geometry Nodes (free)
  • Materials: Quixel Megascans (10,000+ PBR materials, all FREE)

See FREE_CONTENT_GENERATION_GUIDE.md for complete workflows and tutorials.

Project Structure

Adastrea/
├── README.md                # Project overview
├── ROADMAP.md              # Development roadmap
├── ARCHITECTURE.md          # MVP architecture
├── LICENSE                  # MIT License
│
├── docs/                    # All documentation
│   ├── CHANGELOG.md         # Version history
│   ├── GETTING_STARTED.md   # Setup guide
│   ├── QUICKSTART.md        # Quick start
│   ├── DOCUMENTATION_INDEX.md # Doc index
│   ├── development/         # Development guides
│   ├── mvp/                 # MVP documentation
│   └── archive/             # Archived docs
│
├── Assets/                 # YAML templates (deferred systems)
├── Blueprints/             # Blueprint documentation
├── Config/                 # Unreal Engine configuration
│
├── Content/                # Game content (UE assets)
│   ├── Blueprints/        # Blueprint classes
│   ├── Homeworlds/        # Homeworld assets
│   ├── Maps/              # Level maps
│   ├── Planets/           # Planet assets
│   ├── SpaceStations/     # Station assets and modules
│   └── UI/                # UI widgets
│
├── Python Scripts/         # Automation and testing
│   ├── SmokeTest.py           # Smoke testing script
│   ├── ScreenshotTester.py    # Screenshot and visual regression testing
│   ├── AutomationRunner.py    # CLI automation orchestrator
│   ├── AdastreaAssetValidator.py  # Asset validation
│   ├── EditorUtilities.py     # Editor utility functions
│   ├── ScenePopulator.py      # Automated scene population
│   ├── InteriorLayoutPopulator.py # Interior layout automation
│   ├── ProceduralGenerators.py # Procedural content generation
│   ├── TemplateGenerator.py   # YAML template generator
│   ├── GuideGenerator.py      # Documentation generator
│   ├── YAMLtoDataAsset.py     # YAML import tool
│   ├── SetupCheck.py          # Environment validation
│   ├── PopulationTemplates/   # Scene population config templates
│   ├── smoke_test_config.json      # Smoke test configuration
│   ├── screenshot_test_config.json # Screenshot test configuration
│   └── automation_config.json      # Automation runner configuration
│
└── Source/                 # C++ source code
    ├── Adastrea/          # Core game systems
        ├── AI/            # AI logic classes
        ├── Characters/    # Character and personnel
        ├── Factions/      # Faction system
        ├── Materials/     # Material system
        ├── Planets/       # Planet classes
        ├── Player/        # Player-specific systems
        ├── Ships/         # Spaceship classes
        ├── Stations/      # Space station classes
        ├── Trading/       # Trading economy
        └── UI/            # UI widgets

Core Features

Spaceship Data Asset System

A comprehensive spaceship specification system that allows designers to create detailed ship configurations as Blueprint Data Assets without writing C++ code. The base ASpaceship class includes FloatingPawnMovement for 3D space flight capabilities.

Key Components:

  • ASpaceship - Base ship actor with FloatingPawnMovement component for space flight
  • USpaceshipDataAsset - Complete ship specification data asset with all stat categories
  • Core Stats: Hull strength, cargo capacity, crew requirements, modular points
  • Combat Stats: Armor, shields, weapons, point defense systems
  • Mobility Stats: Speed, acceleration, maneuverability, jump range, fuel
  • Utility Stats: Sensors, stealth, repair, science, medical systems
  • Operational Stats: Power, life support, maintenance, hangars, drones, AI
  • Advanced Stats: Diplomacy, boarding, customization slots, electronic warfare, mining
  • Lore/Flavor: Manufacturer, year built, rarity tier, colors, lore notes

Ship Templates Available:

  • Pathfinder Scout - Fast reconnaissance vessel with exceptional sensors
  • Warhammer Gunship - Heavy combat ship with devastating firepower
  • Merchant Trader - Large cargo hauler optimized for trade routes
  • Starliner Luxury - Premium passenger vessel with diplomatic facilities
  • Excavator Mining - Industrial mining barge with resource extraction tools
  • Sovereign Command - Capital flagship with command and carrier operations

Blueprint-Callable Functions:

  • GetCombatRating() - Calculate overall combat effectiveness (0-100)
  • GetMobilityRating() - Calculate overall mobility (0-100)
  • GetUtilityRating() - Calculate overall utility (0-100)
  • IsSuitableForRole(Role) - Check if ship fits a specific role
  • GetSizeCategory() - Get ship size classification
  • GetOperationalCost() - Calculate daily maintenance cost

Documentation:

Quick Usage:

  1. Create a new SpaceshipDataAsset in the Content Browser
  2. Use YAML templates from Assets/SpaceshipTemplates/ as reference
  3. Configure all stat categories (core, combat, mobility, utility, operational, advanced, lore)
  4. Test with Blueprint-callable helper functions
  5. Integrate into your spaceship Blueprint actors

Space Station Editor System

A modular space station construction system that enables players to build, customize, and manage space stations in-game. The system uses Blueprint-friendly C++ classes and is provided through the StationEditor runtime module.

Key Components:

  • ASpaceStation - Core station actor with module management (add, remove, move modules) [Adastrea module]
  • ASpaceStationModule - Base class for station modules with type classification [Adastrea module]
  • UStationEditorManager - Core C++ manager handling placement, validation, undo/redo, construction queue [StationEditor module]
  • UStationModuleCatalog - Data Asset defining available modules, costs, and requirements [StationEditor module]
  • UStationEditorWidget - Player-facing UI widget for station editing [StationEditor module]
  • AStationBuildPreview - Visual preview actor showing placement validity [StationEditor module]
  • UStationGridSystem - Grid snapping and alignment system [StationEditor module]
  • EStationModuleGroup - Module categorization enum (Docking, Power, Storage, Defence, etc.) [Adastrea module]

Module Organization:

  • StationEditor module (Runtime): In-game player-facing station editor UI with full editing capabilities
  • Adastrea module (Runtime): Core station and module actors
  • PlayerMods module (Runtime): Player modification system

Documentation:

Quick Usage:

  1. Create Blueprint extending ASpaceStation for your custom station
  2. Create module Blueprints extending ASpaceStationModule (e.g., docking bays, trade hubs)
  3. Create DA_StationModuleCatalog Data Asset with available modules
  4. Create Widget Blueprint extending UStationEditorWidget for the in-game editor UI
  5. In your Player Controller Blueprint:
    • Set StationEditorWidgetClass to your widget (e.g., WBP_StationEditor)
    • Set ModuleCatalog to your catalog data asset
  6. Bind a key (e.g., M) to call ToggleStationEditor() - the C++ implementation handles everything automatically!
  7. New in 2025: All editor opening logic is now in C++ - see Migration Guide

Way System

The Way System provides specialized guilds (Ways) and micro-alliances (Way Networks) based on shared values (Precepts). Ways are small focused organizations (50-1000 members) that handle specific industries and form networks where reputation with one member affects the entire alliance.

Key Components:

  • UWayDataAsset - Specialized guild definition with industry, quality, and Precepts
  • UWayNetworkDataAsset - Micro-alliance of 2-5 Ways with shared values
  • UVerseSubsystem - Global network management and reputation tracking
  • UVerse - Player component tracking Way reputation and completed Feats
  • Reputation Spillover - Actions with one network member affect all members
  • Network Bonuses - Reputation multipliers for aligned accomplishments

Advanced Features:

  • Industry Specialization: 15 industry types (Mining, Manufacturing, Exploration, etc.)

    • Each Way focuses on specific production/consumption
    • Supply chain relationships between Ways
    • Quality reputation tiers (Basic to Legendary)

  • Way Networks: Micro-alliances of 2-5 Ways

    • Blueprint-callable functions: RegisterNetwork(), GetNetworksForWay(), GetNetworkVerseScore()
    • Shared Precepts (values) unite network members
    • Configurable spillover (20-70% typical)
    • Network bonuses (1.5-2.5x multipliers)
    • Minimum reputation thresholds for benefits

  • Precepts and Feats: Value-driven reputation system

    • Precepts: Core values (Craftsmanship, Discovery, Honor, etc.)
    • Feats: Legendary accomplishments that grant reputation
    • Alignment-based rewards (matching Precepts earn more rep)
    • Automatic network spillover with RecordFeatWithNetworkEffects()

  • Sector Councils: Practical governance (not political)

    • Ways participate in sector decision-making
    • Tax rates and budget allocation
    • Weighted voting based on influence
    • Players can join councils through Way leadership

  • Economic Integration: Supply chains and trading

    • Ways produce and consume resources
    • Trade agreements and pricing
    • Network member trading bonuses
    • Joint contracts for high-reputation players

Example Networks:

  • Craftsmen's Compact - Engineering excellence (Engineers, Ship-Builders, Refiners)
  • Frontier Alliance - Exploration and discovery (Scouts, Cartographers, Pioneers)
  • Honor Circle - Warrior traditions (Warriors, Duelists, Protectors, Bounty Hunters)
  • Merchant Coalition - Trade and commerce (Traders, Brokers, Transport Union)
  • Scholars' Syndicate - Knowledge and research (Researchers, Archivists, Scientists)

Documentation:

Quick Usage:

Creating a Way:

  1. Create a new WayDataAsset in the Content Browser
  2. Configure identity (name, ID, description)
  3. Set specialization (industry, quality tier, member count)
  4. Define Core Precepts (3-5 values with importance levels)
  5. Add produced/consumed resources for supply chains
  6. Set organizational attributes (tech, military, economic, influence)

Creating a Network:

  1. Create a new WayNetworkDataAsset in the Content Browser
  2. Add 2-5 member Ways with influence and commitment levels
  3. Define Shared Precepts (copy from member Ways)
  4. Configure spillover percentage (30-50% typical)
  5. Set network alignment bonus (1.5-2.0x typical)
  6. Set minimum reputation threshold (20-40 typical)
  7. Register network with VerseSubsystem on game start

Using in Gameplay:

  • Complete Feats aligned with Way Precepts to earn reputation
  • Reach reputation thresholds to access network bonuses
  • Gain spillover reputation with entire network automatically
  • Access network-exclusive missions, discounts, and rewards
  • Participate in sector council decisions as Way leader

Faction and Personnel AI System

The game includes a complete AI framework for data-driven faction and personnel behaviors, supporting peaceful/exploration early-game priorities and personality-driven decision making.

Key Components:

  • UNPCLogicBase - Base class for all NPC AI logic with BlueprintNativeEvent hooks
  • UFactionLogic - Faction-level strategic AI (macro decisions: expansion, trade, diplomacy)
  • UPersonnelLogic - Individual crew AI (micro decisions: tasks, social, training)
  • Early Game Priorities - Configurable peaceful/exploration focus for factions
  • 8 Personality Dispositions - Cautious, Bold, Analytical, Empathetic, Pragmatic, Curious, Disciplined, Creative
  • Truces and Relationships - Diplomatic systems for peaceful gameplay
  • Task Priorities - Dynamic daily scheduling for personnel based on personality

Advanced Features:

  • Blueprint-Friendly Extension: All AI logic uses BlueprintNativeEvent pattern

    • Override any behavior in Blueprints without C++ knowledge
    • Call parent implementation when needed
    • Mix C++ performance with Blueprint flexibility

  • Peaceful Early-Game AI: Factions support exploration-focused gameplay

    • Configurable priority system (0-10 scale for each activity)
    • Automatic transition from early to mid/late game
    • Truce system for maintaining peace
    • Trade and diplomacy emphasis over conflict

  • Personality-Driven Personnel: 8 dispositions affect all decisions

    • Curious: Exploration and research focus
    • Disciplined: Protocol adherence, by-the-book
    • Empathetic: People-focused, supportive
    • Pragmatic: Efficiency and results
    • Bold: Risk-taking, decisive
    • Cautious: Safety-first, methodical
    • Analytical: Logic and calculation
    • Creative: Innovation and unconventional solutions

  • Social and Relationship Systems: Dynamic crew interactions

    • Friendship and rivalry development
    • Personality compatibility affects collaboration
    • Morale impacts based on social dynamics
    • Command hierarchy with manager/report relationships

YAML Templates:

  • FactionAI/PeacefulExplorers.yaml - Exploration-focused peaceful faction
  • FactionAI/TradeCoalition.yaml - Commerce-focused merchant faction
  • PersonnelAI/CuriousExplorer.yaml - Inquisitive science officer
  • PersonnelAI/DisciplinedSecurity.yaml - By-the-book security officer
  • PersonnelAI/EmpatheticMedic.yaml - Caring medical officer

Documentation:

Quick Usage:

Creating Faction AI:

  1. Create a FactionDataAsset with traits and relationships
  2. Create a Blueprint based on UFactionLogic
  3. Assign FactionDataAsset and configure Early Game Priorities
  4. Override BlueprintNativeEvents to customize behavior (optional)
  5. Integrate with ships/stations via component or reference

Creating Personnel AI:

  1. Create a PersonnelDataAsset with skills, traits, and relationships
  2. Create a Blueprint based on UPersonnelLogic
  3. Assign PersonnelDataAsset and set Disposition
  4. Override BlueprintNativeEvents for custom personality (optional)
  5. Add to character actors and update in Tick

For Designers (No C++ Required):

  • Use YAML templates as reference for values
  • Configure all behavior through Data Assets
  • Customize decisions in Blueprint visual scripting
  • Test and iterate without recompiling
  • All AI hooks are BlueprintNativeEvents

Personnel Management System

The game includes a comprehensive personnel/crew management system for creating and managing crew members, staff, and character progression.

Key Components:

  • UPersonnelDataAsset - C++ Data Asset class for defining personnel with 31 role types
  • FPersonnelTrait - Struct for personnel traits with gameplay modifiers
  • FPersonnelRelationship - Struct for interpersonal relationships
  • FPersonnelSkill - Struct for skill tracking with levels and experience
  • FPerformanceMetric - Struct for tracking effectiveness over time
  • 7 ready-to-use YAML templates for common roles

Advanced Features:

  • Role System: 31 distinct roles from Captain to Janitor

    • Command: Captain, XO, Station Manager
    • Flight: Pilot, Navigator
    • Technical: Engineer, AI Operator, Researcher
    • Combat: Gunnery Chief, Gunner, Security Officer
    • Medical: Medical Officer, Science Officer
    • Support: Quartermaster, Chef, Bartender, Janitor
    • Specialized: Diplomat, Trader, Salvage Specialist, Mining Specialist, Smuggler
    • General: Crew Member, Station Staff, Entertainment, Civilian, Ambassador

  • Skill System: Multi-level skill tracking with experience points

    • Blueprint-callable functions: GetSkillByName(), GetSkillLevel(), HasSpecialty()
    • Individual skill levels (1-10) and experience points
    • Support for skill progression and career development

  • Status Tracking: Comprehensive personnel condition monitoring

    • Health, Morale, Fatigue, Loyalty, Reputation
    • Blueprint-callable functions: IsInGoodCondition(), NeedsRest(), IsLoyal(), HasLowMorale()
    • Real-time status affects performance

  • Relationship System: Track interpersonal connections

    • Friend, Rival, Mentor, Professional, Family relationships
    • Relationship strength (-100 to 100)
    • Blueprint-callable functions: IsFriendsWith(), IsRivalWith(), GetRelationshipStrength()

  • Performance Metrics: Track effectiveness and career history

    • Multiple customizable performance metrics
    • Trend tracking (improving/declining)
    • Past assignments with ratings
    • Blueprint-callable functions: GetPerformanceMetric(), GetAveragePerformance(), IsPerformingWell()

  • Command Hierarchy: Build organizational structures

    • Manager/Direct Report relationships
    • Department assignment
    • Role-based queries: IsInLeadershipRole(), IsInCombatRole(), GetDirectReportCount()

  • Employment System: Contract and compensation management

    • Salary tracking
    • Contract duration and remaining time
    • Employment history

  • Trait System: Unique characteristics with gameplay modifiers

    • Blueprint-callable functions: HasTrait(), GetTraitModifier(), GetTraits()
    • Support for stacking modifiers
    • Personality types and descriptions

YAML Templates:

  • Captain.yaml - Ship commander template with leadership stats
  • Pilot.yaml - Flight operations specialist
  • Gunner.yaml - Weapons operator template
  • Engineer.yaml - Technical specialist template
  • MedicalOfficer.yaml - Healthcare provider template
  • StationManager.yaml - Station operations manager
  • CrewMember_Generic.yaml - General crew member template

Documentation:

Quick Usage:

  1. Create a new PersonnelDataAsset in the Content Browser
  2. Configure personnel properties (role, skills, status, relationships, traits)
  3. Use YAML templates as reference for typical values and structure
  4. Assign to ships/stations via CurrentAssignment property
  5. Use Blueprint-callable functions to query personnel data in gameplay
  6. Build command hierarchies using Manager ID and Direct Reports
  7. Create relationships between personnel for team dynamics

Additional Core Systems

Combat System - Complete weapon, targeting, and damage mechanics with 6 weapon types, directional shields, point defense, and 5-phase boarding. See Assets/CombatSystemGuide.md.

Navigation System - Autopilot, 3D pathfinding, and AI following behavior. Supports multi-waypoint paths with obstacle avoidance. See Assets/NavigationSystemGuide.md.

Quest System - Mission tracking with 10 quest types and 9 objective types. Supports quest chains, procedural generation, and difficulty-scaled rewards. See Assets/QuestSystemGuide.md.

Enhanced Input System - Centralized input configuration with 30+ actions organized into categories (Movement, Combat, Navigation, System, Camera). See Assets/EnhancedInputImplementation.md and Assets/MousewheelThrottleSetupGuide.md for detailed mousewheel throttle control setup in UE 5.6.

Save System - Complete save/load with multiple slots, auto-save, metadata tracking, and version control. See Assets/SaveSystemGuide.md.

Tutorial System - Interactive tutorials with 6 step types (Message, UI Highlight, Wait for Action, etc.). Progress tracking and designer-friendly. See Assets/TutorialSystemGuide.md.

Audio System - Sound effects with 8 categories and dynamic music system with 8 moods. Includes spatial audio and priority management. See Assets/AudioSystemGuide.md.

Player Progression - Leveling, reputation tracking, ship upgrades, and unlock systems. See Assets/PlayerProgressionGuide.md.

UI Systems - Complete HUD (AdastreaHUDWidget), Ship Status Screen (ShipStatusWidget), Inventory management (InventoryWidget), Ship Customization (ShipCustomizationWidget), Trading interface (TradingInterfaceWidget), and Station Management (StationManagementWidget). See Assets/ShipStatusScreenSetup.md for ship status screen setup and system-specific guides in Assets/.

Map System

A comprehensive navigation system for displaying the universe and individual sectors with exploration tracking.

Key Components:

  • UniverseMapWidget - Galaxy-level view showing all sectors organized in a 3D grid
  • SectorMapWidget - Detailed view of individual sectors with object listings
  • Sector Discovery - Track explored vs unexplored regions
  • Player Tracking - Automatically locate and display player's current sector
  • Grid Organization - Sectors organized based on world position (200km per cell)
  • Exploration Progress - Statistics showing percentage of universe discovered

Features:

  • Full Blueprint exposure with BlueprintNativeEvent pattern
  • Automatic sector discovery as player explores
  • Neighboring sector finding and distance calculations
  • Random spawn position generation within sectors
  • Integration with quest markers and faction territories
  • Customizable visibility for undiscovered sectors

Usage: Create Widget Blueprints based on UniverseMapWidget and SectorMapWidget classes, design the UI layout, and bind to player controller for map toggle (M key recommended).

Documentation:

Performance Tools - LOD management (LODManagerComponent) and performance profiling (PerformanceProfiler). See Assets/PerformanceOptimizationGuide.md.

Documentation

Plugin & Tool Integration

Project Planning

  • Project Roadmap - Development phases, timelines, and future features
  • Stub and Placeholder Audit - ⭐ Complete audit of stubs, placeholders, and TODOs - realistic assessment of remaining work
  • Current Status - Realistic project status assessment (code 85% complete, content 10% complete)

Research and Analysis

Visual Design

  • Game Mockups - Comprehensive visual mockups showing current vs. desired UI/UX for all game screens
  • Interactive UI Demo - HTML/CSS interactive demo of game interfaces (open in browser)

Developer Documentation

Comprehensive technical documentation for contributors and developers:

Build and CI/CD Documentation

Quick Start Guides

Blueprint Documentation

System Documentation

Core Systems

Advanced Systems

Templates and References

Integration Guides

Workflows and Best Practices

Editor Development

Note: The AdastreaEditor C++ module has been removed, but AdastreaEditor.Target.cs is included for building the project in Unreal Editor. Future editor customizations can be added as a new module if needed.

YAML Templates

All systems include ready-to-use YAML templates in their respective folders:

  • Assets/SpaceshipTemplates/ - Ship configurations
  • Assets/FactionAITemplates/ - Faction AI behaviors
  • Assets/PersonnelAITemplates/ - Personnel AI personalities
  • Assets/PersonnelTemplates/ - Crew member profiles
  • Assets/TradingTemplates/ - Trade items and markets

Contributing

We welcome contributions! Here's how to get started:

  1. Read the Guidelines: See docs/development/CONTRIBUTING.md for detailed instructions
  2. Check Issues: Look for issues labeled "good first issue" or "help wanted"
  3. Fork & Clone: Fork the repository and create a feature branch
  4. Make Changes: Follow our coding standards and best practices
  5. Test Thoroughly: Ensure your changes work in-editor
  6. Submit PR: Open a pull request with a clear description

Ways to Contribute

  • 🐛 Bug Reports: Found a bug? Open an issue with reproduction steps
  • ✨ New Features: Have an idea? Discuss it in an issue first
  • 📚 Documentation: Improve guides, fix typos, add examples
  • 🎨 Assets: Create example ships, factions, or other content
  • 🧪 Testing: Help test features and report issues

Code of Conduct

Be respectful, constructive, and welcoming. We're all here to build something great together!

License

This project is licensed under the MIT License - see the LICENSE file for details.

Version History

See docs/CHANGELOG.md for detailed version history and release notes.

Support

  • Documentation Issues: Open an issue with the "documentation" label
  • Bug Reports: Use the bug report template
  • Feature Requests: Use the feature request template
  • General Questions: Start a discussion in the repository

Built with ❤️ using Unreal Engine