Framework Name Convention for Objects and Files

Table of Contents

• 1. Developer Code Conventions: DEBCF Mod Project
• 2. Prefix Global Architecture Rule
  • 2.1. Core Rules
• 3. Mandatory Development Core Rules
• 4. Best Practice Naming Scheme Recommendations
• 5. Critical Engine Limitations and Design Warnings
• 6. Critical Cross Platform Compatibility Rules
• 7. Component Matrix Logic Foundations
• 8. Component Matrix Art Assets and Memory Variables
• 9. Component Matrix Structural Databases
• 10. Component Matrix Fleet and System Rules
• 11. Component Matrix Unlock Elements and Council Systems
• 12. Component Matrix Leaders Exploits Diplomatic Treaties and Warfare Operations
• 13. Context Matrix Execution Scopes Entity Pointers
• 14. Understanding Engine Overriding Mechanisms
  • 14.1. Directory Loading Rules Table
• 15. Important Mod Load Order Filename Strategies
  • 15.1. Load Priority Filename Blueprints
• 16. Advanced Localisation Strategy for Frameworks
  • 16.1. Contextual Suffix Blueprint Blueprint
• 17. Dynamic Interoperability and Mod Detection Loops
  • 17.1. Using Scripted Variables and Inline Scripts for Mod Compatibility

---

---

This Wiki page was last updated for $$\textcolor{aqua}{Stellaris}$$ version v4.4.*

---

---

1. Developer Code Conventions: DEBCF Mod Project

Welcome to the centralized Name Convention for Objects and Files layout for the DEBCF Mod Project.

The DEBCF uses the same File & Name Convention scheme everywhere.

To guarantee modular stability, maximize human readability during cross-team debugging, and fully eliminate mod compatibility file-overwrite conflicts, follow this structure.

You can see The Database of all existing Files and Objects in Framework Object & File Database wiki page.

2. Prefix Global Architecture Rule

Every script filename, dynamic variable pointer, custom user interface element, and localized text key MUST adhere to this precise layout:

DEBCF_<OBJECT_TYPE>_<USAGE_SCOPE>_<detailed_purpose>

2.1. Core Rules

1. Case Contrast Requirement: Structural metadata keys (DEBCF, OBJECT_TYPE, USAGE_SCOPE) MUST stay strictly UPPERCASE. The trailing detailed_purpose custom logic string MUST be lowercase.
2. No Segment Chaining Underscores: Do not use internal underscores inside tags (use GVAR, not GLOBAL_VAR). Underscores are reserved strictly to separate the main modular segments.

3. Mandatory Development Core Rules

To ensure flawless runtime execution, every developer on the project must adhere to these engine stability laws:

$$\text{\textcolor{red}{1. Namespace Declarations:}}$$ Every file inside the events/ folder MUST establish a clean all-uppercase namespace header matching your event prefix (e.g., namespace = DEBCF_EVENT_COUNTRY).

$$\text{\textcolor{red}{2. Dynamic Cleanup:}}$$ Any TTARGET or runtime SVAR initialized inside an event block MUST be systematically cleared out or set to 0 once execution leaves that scope block.

$$\text{\textcolor{red}{3. No Raw Vanilla Overwrites:}}$$ Never touch vanilla mod assets directly. Use object merging or explicit load order file injections to safely introduce custom changes.

$$\text{\textcolor{red}{4. Trigger Validation:}}$$ Every custom EFFECT script that manipulates economy values or moves fleets MUST be wrapped in an explicit TRIGGER validation block to prevent sudden crash-to-desktop errors.

4. Best Practice Naming Scheme Recommendations

Note

$$\text{\textcolor{cyan}{THE TRAILING ACTION ANCHOR}}$$ Always place your core action verb at the absolute end of your lowercase <detailed_purpose> string (e.g., _spawn_check, _cooldown_reset). This ensures that when your text editor organizes assets alphabetically, all identical functional tasks are grouped together naturally.

Important

$$\text{\textcolor{cyan}{CONTEXT NOUN ANCHORING}}$$ For massive mods, structure your purpose string by moving from general category down to specific mechanics. This creates self-sorting hierarchies inside your scripts.

• Excellent Structure: DEBCF_EVENT_COUNTRY_crisis_nanite_rebellion
• Poor Structure: DEBCF_EVENT_COUNTRY_nanite_rebellion_crisis

Tip

$$\text{\textcolor{cyan}{THE SINGLE-UNDERSCORE STANDARD}}$$ Sticking to single underscores ensures clean parsing by third-party syntax tools like CWTools and keeps your code visually unclaimed, maximizing your total character budget headroom.

5. Critical Engine Limitations and Design Warnings

Warning

$$\text{\textcolor{orange}{THE 64-CHARACTER MEMORY TRUNCATION CLIFF}}$$ Stellaris hardcaps dynamic string data registers at 64 characters max. While the file loader reads filenames up to 256 characters, internal runtime engines handling GFLAG, SFLAG, SVAR, and GTARGET silently truncate anything past 64 characters in save files. Keep your lowercase <detailed_purpose> under 20 characters to guarantee save stability! Note: On GitHub, this Warning block is Brown; look below for severe errors.

Caution

$$\text{\textcolor{red}{CRITICAL DATA CORRUPTION HAZARD (RED HIGH-PRIORITY)}}$$ Exceeding character budgets or failing to use clean single-underscore separators breaks database index tracking. This triggers permanent save game corruption, game engine logic loops, and immediate user CTD (Crash-To-Desktop). Treat this limitation as an absolute structural ceiling across all project files.

Note

$$\text{\textcolor{cyan}{ALPHABETICAL IDE GROUPING STRATEGY}}$$ Structure your lowercase <detailed_purpose> string starting with a noun, moving toward a specific verb.

• Good Structure: DEBCF_EVENT_COUNTRY_fleet_spawn
• Bad Structure: DEBCF_EVENT_COUNTRY_spawn_a_fleet

6. Critical Cross Platform Compatibility Rules

Because many players use Linux or Steam Deck (SteamOS), your code must adhere to strict filesystem constraints. Windows is case-insensitive, while Linux is aggressively case-sensitive.

Caution

$$\text{\textcolor{red}{CROSS-PLATFORM FILE PATH MUTATION (RED HIGH-PRIORITY)}}$$ All physical modded files on disk MUST retain standard uppercase structures for tags but strict lowercase extensions.

• Valid File Path: DEBCF_EVENT_COUNTRY_crisis_loop.txt
• Broken Linux Path: DEBCF_EVENT_COUNTRY_crisis_loop.TXT (Will crash Linux clients instantly) Any cross-reference inside scripts to .dds art textures or .txt paths must mirror the directory casing with 100% precision.

Warning

$$\text{\textcolor{orange}{LOCALISATION FILE ENCODING ENFORCEMENT}}$$ All .yml localisation files MUST be explicitly saved in UTF-8 with BOM (Byte Order Mark) formatting. Vanilla parsing compilation on Linux treats raw UTF-8 files as unreadable garbage, causing layout strings to break and display raw code anchors to the player. Enforce UTF-8 with BOM inside your text editor.

7. Component Matrix Logic Foundations

Use these UPPERCASE identifiers inside the <OBJECT_TYPE> slot when declaring baseline engine rules.

Acronym Key	Type Meaning	Paradox Engine Directory Target
EVENT	Custom Events Engine	events/
ACTION	Custom On Actions Hooks	common/on_actions/
INLINE	Inline Script Includes	common/inline_scripts/
SEFFECT	Scripted Macro Effects	common/scripted_effects/
STRIGGER	Scripted Macro Triggers	common/scripted_triggers/
GUI	Custom Event UI Layouts	interface/
BUTTON	Clickable UI Button Assets	interface/ (Buttons / Layouts)
ERROR	Diagnostic Engine Errors	Called via 'log_error' effect
LOCKEY	Custom Localisation Keys	localisation/english/
SLOCKEY	Dynamic Script Localisation	common/scripted_localisation/

8. Component Matrix Art Assets and Memory Variables

Use these UPPERCASE identifiers inside the <OBJECT_TYPE> slot when declaring art assets or runtime data blocks.

Acronym Key	Type Meaning	Paradox Engine Directory Target
GFX	Interface Art Definition	interface/ (.gfx asset maps)
SOUND	Sound Effects / Music Hooks	sound/ (.sfx references)
GVAR	Scripted Global Variable Constant	common/scripted_variables/ (@xxx)
LVAR	Scripted Local Variable Macro	File-bound macro string block
SVAR	Scope Saved Variable	Dynamic runtime tracking variables
GFLAG	Engine Global Flag	Galaxy-wide binary game-state switches
SFLAG	Context Scope Flag	Entity-locked binary state switches
GTARGET	Global Event Target	Persistent multi-event pointer memory
TTARGET	Temporary Event Target	Volatile block-isolated pointer memory
ECHAIN	Event Chain Tracking Blocks	common/event_chains/

9. Component Matrix Structural Databases

Use these identifiers for the <OBJECT_TYPE> slot when declaring economy infrastructure.

Acronym Key	Database Target Type	Paradox Directory Reference
POLICY	Empire-Wide Legal Policies	common/policies/
BUILDING	Planetary Infrastructure	common/buildings/
JOB	Pop Job Classes	common/pop_jobs/
DISTRICT	Economy World Districts	common/districts/
DEPOSIT	Planetary Resource Deposits	common/deposits/
RESOURCE	Strategic Trade Commodities	common/strategic_resources/
MARKET	Galactic Market Configuration	common/galactic_market/
ECOCAT	Resource Modifier Category Rules	common/economic_categories/

10. Component Matrix Fleet and System Rules

Use these identifiers for the <OBJECT_TYPE> slot when declaring naval rules, system vectors, or logic overrides.

Acronym Key	Database Target Type	Paradox Directory Reference
STARBASE	Starbase Modules & Buildings	common/starbase_modules/
RESOLUTION	Galactic Community Laws	common/resolution_categories/
FLEETTEMPL	Automated Fleet Behavior Maps	common/fleet_templates/
THREATTYPE	Inter-Empire Threat Metrics	common/threat_types/
GAMERULE	Hardcoded Core Engine Laws	common/game_rules/
MESSAGE	Diplomatic & Game Alerts	common/message_types/
SOLSYSTEM	Star System Map Initializers	common/solar_system_initializers/
SECTOR	Sector Cluster Infrastructure	common/sectors/
CALENDAR	Game Ticking Speed Matrix	common/game_speed/

11. Component Matrix Unlock Elements and Council Systems

Use these definitions for the <OBJECT_TYPE> slot when introducing character sheets, council positions, and development unlocks.

Acronym Key	Gameplay Component	Engine Registry Target
EDICT	Empire Decrees & Edicts	common/edicts/
DECISION	Planetary Long-Term Decisions	common/decisions/
SITUATION	Dynamic Situation Framework	common/situations/
SITUATIONMOD	Situation Modifier Categories	common/situation_modifier_categories/
TECHNOLOGY	Research Technologies Tree	common/technology/
TRADITION	Tradition Tree Branches	common/traditions/
PERK	Ascension Perks Matrix	common/ascension_perks/
CIVIC	Government Empire Civics	common/government/civics/
ORIGIN	Empire Starting Origins	common/governments/origins/
RELIC	Collectible Relics / Trophies	common/relics/
CAGENDA	Council Agenda System Unlocks	common/council_agendas/
MANDATE	Democratic Ruler Objectives	common/mandates/
CPOSITION	Council Member Seat Types	common/councilor_positions/

12. Component Matrix Leaders Exploits Diplomatic Treaties and Warfare Operations

Use these definitions when designing characters, anomaly systems, ship modules, or spy actions.

Acronym Key	Gameplay Component	Engine Registry Target
LEADERROLE	Leadership Core Assignments	common/leader_roles/
LEADERCLASS	Character Classes Modifiers	common/leader_classes/
LEADERBACK	Leader Background Origins	common/leader_backgrounds/
PERSONALITY	Leader Sheet Personality Traits	common/leader_personality_traits/
TRAIT	Leader or Species Traits	common/traits/
SPYOPERATION	Espionage Network Actions	common/espionage_operation_types/
ASTRALRIFT	Astral Rifts Sub-Systems	common/astral_rifts/
RIFTINHABIT	Astral Plane Entity Types	common/rift_inhabitants/
ANOMALY	Exploration Space Anomalies	common/anomalies/
ARCHAEOLOGY	Planetary Digsites Layers	common/archaeological_sites/
SPECIALPROJ	Mid-Game Project Tech Trees	common/special_projects/
WEATHER	Space Hazards / Cosmic Storms	common/cosmic_storms/
WEAPONCOMP	Tactical Weapon Attachments	common/component_templates/
UTILITYCOMP	Shield/Armor Utility Assets	common/component_templates/
COMPONENTSET	Ship Module Structural Sets	common/component_sets/
CLOAKING	Cloaking Module Framework Rules	common/component_templates/
MEGABUILD	Megastructure Construct Stages	common/megastructures/
FACTION	Internal Pop Political Groups	common/pop_factions/
AGREEMENT	Subject Agreement Treaties	common/agreements/
BAZAAR	Merchant Enclave Tradeposts	common/bazaars/

13. Context Matrix Execution Scopes Entity Pointers

Use these specific designators inside the <USAGE_SCOPE> slot to lock script block contexts.

Acronym Key	Stellaris Engine Context	Scope Target Details
NOSCOPE	Absolute Global Space	Game Engine Root / Multiple Target Blocks
GLOBAL	Galaxy Map Layer	Galaxy Setup / Star System Initializers
COUNTRY	Sovereign Empire Focus	Government / Sovereign Empires
COUNCIL	Imperial Central Government	Ruler Cabinets / Council Positions
SECTOR	Sub-Regional Administration	Core & Frontier Sector Layouts
SYSTEM	Star System Coordinates	Solar Coordinates / Starbases
PLANET	Celestial Worlds / Habitats	Planetary Surface Layer / Districts
MEGASTRUC	Megastructures Structures	Dyson Spheres / Ringworld Segments
FLEET	Combined Flotillas	Organized Fleets / Armadas / Strike Groups
SHIP	Single Vessel Asset	Ship Hulls / Section Slot Math / Hangar Modules
LEADER	Appointed Character Entities	Scientists / Admirals / Paragons / Officials
SPECIES	Biological/Synthetic DNA	Species Archetypes / Subspecies Templates
POP	Working Class Subunits	Pop Jobs / Faction Strata / Habitability
AGENTS	Espionage Infiltration Units	Asset Operations / Active Infiltrators
ESPIONAGE	Empire Intelligence Networks	Global Spy Network Containers
FEDERATION	Multilateral Alliances	Federation Types / Joint Level Progress
GALCOM	Galactic Senate Assembly	Senate Sanctions / Imperium Resolutions
ARCHAEOLSITE	Excavation Sites Context	Chapter Ticks / Site Modifiers
RIFTSPACE	Astral Plane Layer Context	Rift Dimensions / Astral Choices

Important

SCOPE VERIFICATION LAW Passing an event or effect call into an invalid target scope context will immediately crash execution for that block or generate game engine "null pointer" exceptions in the background logs. Verify target contexts using the CWTools validation layer prior to branch commits.

14. Understanding Engine Overriding Mechanisms

Stellaris uses highly specific file compilation algorithms. How you override base content depends strictly on the Folder Type. Understanding these rules prevents broken scripts!

14.1. Directory Loading Rules Table

Overriding Type	Logic Rule Definition	Paradox Folder/File Application
FIOS (First In Only Served)	The file loaded first via mod load order wins. Duplicate variables/keys processed later are entirely skipped.	Interface Asset files (.gfx), common/graphical_culture/, common/scripted_variables/, common/scripted_localisation/, music/
LIOS (Last In Only Served)	The file loaded last via mod load order wins. Duplicate files completely replace earlier versions.	Scripted Triggers (common/scripted_triggers/), common/threat_types/, common/leader_personality_traits/, common/fleet_templates/
Object Merging	Individual entries inside distinct files append together. Duplicate specific internal block IDs overwrite using load priority.	events/, common/buildings/, common/traits/, common/edicts/, common/game_rules/

Caution

THE REPLACEMENT DIRECTORY RULE (RED HIGH-PRIORITY) localisation/ processing merges text keys non-destructively. Custom mod layout translation keys go in localisation/english/ directly. To forcibly override or alter raw vanilla localization content strings, you MUST place your duplicate keys strictly within a nested localisation/replace/english/ subfolder layout to call the engine's internal LIOS structural replacement routine.

15. Important Mod Load Order Filename Strategies

Because folder compilation acts strictly on alphabetical order, your physical text filenames dictate whether your mechanics apply before or after vanilla assets.

15.1. Load Priority Filename Blueprints

• !_DEBCF_core_variables.txt
  • Priority: Absolute First.
  • Use Case: Forcing global macro variables or scripted localisations to lock first via FIOS mechanics.
• 00_DEBCF_overrides.txt
  • Priority: Standard High Overrule.
  • Use Case: Ensuring custom definitions load cleanly prior to vanilla layout tables.
• DEBCF_content_pack.txt
  • Priority: Standard Native.
  • Use Case: Normal assets (Events, Unlocks, Situations) that append without overwriting.
• z_DEBCF_extensible_framework.txt or zz_DEBCF_ui_core.txt
  • Priority: Dead Last / Lower Override Priority.
  • Use Case 1 (Modular Extensibility): Intentionally allowing sub-mods, compatibility patches, or companion frameworks to overwrite your baseline functions.
  • Use Case 2 (Dynamic Interaction Loops): High-priority mods populate global variables or flag triggers. Your low-priority base file, loading last, scans for their presence at runtime to alter script execution paths or scale specific interface frames automatically.

16. Advanced Localisation Strategy for Frameworks

Because DEBCF acts as a structural framework, localization strings must remain modular so child mods or integration expansions can dynamically pull or format content blocks safely.

16.1. Contextual Suffix Blueprint Blueprint

When building out translation arrays inside your .yml files, adhere to these structural suffixes for text keys:

• _name => Display title of the game database entity. Example: DEBCF_CIVIC_COUNTRY_synthetic_purifiers_name:0 "Synthetic Purifiers"

• _desc => Long-form narrative history or structural flavor description. Example: DEBCF_ORIGIN_COUNTRY_shattered_homeworld_desc:0 "A world forces mechanical adaptation."

• _tooltip => Dynamic mouseover text displaying mechanics or requirements. Example: DEBCF_PERK_NOSCOPE_voidborn_architects_tooltip:0 "Unlocks structural frame algorithms."

• _delayed => Delayed secondary popups providing background lore for choices. Example: DEBCF_EVENT_COUNTRY_nanite_collapse_delayed:0 " Cascading system break registered."

• _error => Warning alert fallback layouts triggered when a framework operation fails. Example: DEBCF_LOCKEY_NOSCOPE_dependency_missing_error:0 "§RCRITICAL ERROR: dependency array corrupted!§!"

17. Dynamic Interoperability and Mod Detection Loops

Using our lower priority alphabetical overrides (z_DEBCF_ / zz_DEBCF_), the framework can dynamically scale, re-route scripting chains, or inject UI elements depending on what other mods are active in a player's playset.

17.1. Using Scripted Variables and Inline Scripts for Mod Compatibility

Convention is $$\textcolor{green}{1}$$ for a present mod, $$\textcolor{red}{0}$$ for an absent mod. These variables can be used to create content conditional on other mods as follows (credit to TTFTCUTS from the Stellaris Modding Den Discord Server for this invention):

inline_script = {
    script = example_conditional_script
    CASE = @example_mod_compat_var
}

In common/inline_scripts/example_conditional_script.txt:

inline_script = example_conditional_script_$CASE$

In common/inline_scripts/example_conditional_script_1.txt:

# 18. script (possibly blank) to include if the mod is present

In common/inline_scripts/example_conditional_script_0.txt:

# 19. script (possibly blank) to include if the mod is absent

More complicated logic is also possible:

CASE = @[1-(example_mod_compat_var * example_mod_compat_var_2)]

This would implement case 1 if neither of two mods was present and case 0 otherwise, for example. Some mods use flexible generic conditional scripts which also take a CONTENTS parameter containing the script to implement in case 1; Scripted Trigger undercoat provides one such set of generic conditional scripts in the stu subfolder.