Config Groups & Config Files

DragonKnightOfBreezeAbout 1640 wordsAbout 5 min

Config Groups & Config Files

Config Group

Summary

PLS implements various advanced language features based on config groups, which consists of many CWT config files.

Config groups can have different sources. For config groups from the same source, there are config groups for different game types, and the core config group, which is shared by all game types.

Reference Links:

Repositories

Sources

Built-in Config Groups

Path: config/{gameType}^[1] (in the plugin jar)
Enabled: Always
Customizable ：No

These config files are from plugin repository and config repositories of each game. Compare to the config files used by CWTools, there are several modifications and extensions.

Local Config Groups

Path: {rootPath}/{gameType}^[1:1] (rootPath need be to be configured in plugin's settings page)
Enabled: Yes if path is existing
Customizable ：Yes

Containing config files are customized by users themselves. Available for all projects. Changes should be confirmed to import manually.

Project Config Groups

Path: .config/{gameType}^[1:2] (in the project root directory)
Enabled: Yes if path is existing
Customizable ：Yes

Containing config files are customized by users themselves. Only available for this project. Changes should be confirmed to import manually.

Overridden Strategy

Configs use the LIOS overridden strategy based on the file path and the config ID.

When reading configs, the plugin will iterate config groups by following order: built-in config groups, local config groups, and project config groups. The core config group is shared by all game types, and will be iterated before the config group for related game type.

For example, if you have written some custom configs in the config file .config/stellaris/modifiers.cwt (which is in the project root directory), it will completely override the built-in modifier configs. Since the built-in modifier configs are located in the config file config/stellaris/modifiers.cwt (which is in the plugin jar), and both of their file path is modifiers.cwt. If these are no content in the custom config file, after applied, the plugin will be unable to resolve any modifier in script files.

CWT Config File

Summary

CWT config file use its own file format, which can be considered as a variant of paradox script language. Its file extension is .cwt.

Syntax

The basic syntax of a CWT config file is as follows:

# both equal sign ('=', '==') and not equal sign ('<>', '!=') can be used as the k-v separator (also available in options)
# properties (options) and values can be mixed in clauses (also available in options)

### documentation comment
## option = option_value
## option_0 = { k = v }
## option_value
prop = {
    # line comment
    k = v
    v
}

Writing CWT Config Files

Summary

In progress.

For more detailed specifications, please refer to the reference links below and the built-in config files.

Reference Links:

Guidance

Specifications

Priorities New in 1.3.7

Priority configs are used to configure the override order for targets (scripted variables, definitions, localisations and complex enums).

priorities = {
    # LHS - file path (relative to game or mod root directory)
    # RHS - priority (available values: "fios", "lios", "ordered", default value: "lios", ignore case)
    
    # file path - path of specific directory (e.g. ""common/on_actions", "common/scripted_variables", "localisation")
    
    # fios - use the one that reads first, ignore all remaining items
    # lios - use the one that reads last (if not specified, use this as default)
    # ordered - reads by order, no overrides
    
    "events" = fios
    # ...
}

System Scopes

TODO

Localisation Locales

TODO

Types and Subtypes

TODO

Declarations

TODO

Enums and Complex Enums

TODO

Dynamic Values

TODO

Aliases and Single Aliases

TODO

Inlines

TODO

Modifiers and Modifier Groups

TODO

Links

TODO

Scopes and Scope Groups

TODO

Localisation Links and Localisation Commands

TODO

Specifications (Extended CWT Configs)

Tips

These configs are mostly provided by users themselves, they can be used to enhance plugin's various language features, such as quick documentation, inlay hints, code highlighting and code completion.

Scripted Variables New in 1.3.5

scripted_variables = {
    # 'x' or 'x = xxx'
    # 'x' can also be a pattern expression (template expression, ant expression or regex)
    
    ### Some documentation
    ## hint = §RSome inlay hint text§!
    x
}

Definitions

definitions = {
    # 'x' or 'x = xxx'
    # 'x' can also be a pattern expression (template expression, ant expression or regex)
    
    ### Some documentation
    ## type = civic_or_origin.civic
    x
    
    # since 1.3.5, scope context related options are also available here
    ## type = scripted_trigger
    ## replace_scopes = { this = country root = country }
    x
}

Game Rules

game_rules = {
    # 'x' or 'x = xxx'
    # 'x' can also be a pattern expression (template expression, ant expression or regex)
    # use 'x = xxx' to override declaration config
    
    ### Some documentation
    ## replace_scopes = { this = country root = country }
    x
}

On Actions

on_actions = {
    # 'x' or 'x = xxx'
    # 'x' can also be a pattern expression (template expression, ant expression or regex)
    
    ### Some documentation
    ## replace_scopes = { this = country root = country }
    ## event_type = country
    x
}

Inline Scripts

inline_scripts = {
    # 'x' or 'x = xxx'
    # 'x' is a inline script expression, e.g., for 'inline_script = jobs/researchers_add', 'x' should be 'jobs/researchers_add'
    # 'x' can also be a pattern expression (template expression, ant expression or regex)
    # use 'x = xxx' to declare context config(s) (add '## context_configs_type = multiple' if there are various context configs)
    # note extended documentation is unavailable for inline scripts
    
    x

    # more detailed examples for declaring context config(s)

    ## context_configs_type = multiple
    x = {
        ## cardinality = 0..1
        potential = single_alias_right[trigger_clause]
        ## cardinality = 0..1
        possible = single_alias_right[trigger_clause]
    }

    # since 1.3.5, scope context related options are also available here

    ## replace_scopes = { this = country root = country }
    x
    
    # since 1.3.6, using single alias at root level is also available here
    
    ## context_configs_type = multiple
    x = single_alias_right[trigger_clause]
}

Example:

Parameters

parameters = {
    # 'x' or 'x = xxx'
    # 'x' is a parameter name, e.g., for '$JOB$', 'x' should be 'JOB'
    # 'x' can also be a pattern expression (template expression, ant expression or regex)
    # use 'x = xxx' to declare context config(s) (add '## context_configs_type = multiple' if there are various context configs)
    
    # since 1.3.6, value of option 'context_key' can also be a pattern expression (template expression, ant expression or regex)
    
    ### Some documentation
    ## context_key = scripted_trigger@some_trigger
    x
    
    # more detailed examples for declaring context config(s)
    
    ## context_key = scripted_trigger@some_trigger
    x = localistion
    
    ## context_key = scripted_trigger@some_trigger
    ## context_configs_type = multiple
    x = {
        localisation
        scalar
    }
    
    # since 1.3.5, scope context related options are also available here
    
    ## context_key = scripted_trigger@some_trigger
    ## replace_scopes = { this = country root = country }
    x
    
    # since 1.3.6, using single alias at root level is also available here
    
    ## context_key = scripted_trigger@some_trigger
    ## context_configs_type = multiple
    x = single_alias_right[trigger_clause]
    
    # since 1.3.12, a parameter's config context and scope context can be specified to inherit from its context
    # e.g. for parameter 'x' with context key 'scripted_trigger@some_trigger', its context is scripted trigger 'some_trigger'
    
    ## context_key = scripted_trigger@some_trigger
    ## inherit
    x
}

Example:

Complex Enum Values

complex_enum_values = {
    component_tag = {
        # 'x' or 'x = xxx'
        # 'x' can also be a pattern expression (template expression, ant expression or regex)
        
        ### Some documentation
        ## hint = §RSome inlay hint text§!
        x
    }
}

Dynamic Values

dynamic_values = {
    event_target = {
        # 'x' or 'x = xxx'
        # 'x' can also be a pattern expression (template expression, ant expression or regex)

        ### Some documentation
        ## hint = §RSome inlay hint text§!
        x

        # since 1.3.9, scope context related options are also available here
        # only receive push scope (this scope), ignore others (like root scope, etc.)

        ## push_scope = country
        x
    }
}

FAQ

About the Template Expression

Template expressions are composed of string literals and expressions of limited types (definitions, enums and dynamic values), and can be used for more flexible matching.

# a string literal, exactly matches 'x'
x
# a template expression which contains a reference to jobs, matches 'a_researcher_b', 'a_farmer_b', etc.
a_<job>_b
# a template expression which contains a references to enum of weight_or_base, matches 'a_weight_b' and 'a_base_b'
a_enum[weight_or_base]_b
# a template expression which contains a references to dynamic value type of anything
# generally, there is no limit for 'value[anything]', so this expression is equivalent to regex 'a_.*_b'
a_value[anything]_b

How to Use the ANT Expression in Config Files New in 1.3.6

Since 1.3.6, the ANT expression can be used for more flexible matching.

# a ant expression use prefix 'ant:'
ant:/foo/bar?/*
# a ant expression use prefix 'ant.i:' (ignore case)
ant.i:/foo/bar?/*

# wildcards in ant expression:
# '?' - used to match any single character
# '*' - used to match any characters (exclude '/')
# '**' - used to match any characters

How to Us Regex in Config Files New in 1.3.6

Since 1.3.6, Regex can be used for more flexible matching.

# a regex use prefix 're:'
re:foo.*
# a regex use prefix 're.i:' (ignore case)
re.i:foo.*

How to Specify the Scope Context in Config Files

In config files, the scope context is specified by option push_scope and replace_scope.

# push 'country' scope to scope stack
# for this example, the next this scope will be 'country'
## push_scope = country
some_config

# replace scopes of specific system scopes into scope context
# not supported for 'prev' system scope (and 'prevprev', etc.)
# for this example, the next this scope will be 'country', so do the next root scope and the next from scope
## replace_scopes = { this = country root = country from = country }
some_config

Importing CWT Config Files

Summary

You can write customized config files in directories of local config groups or project config groups. They are helpful for optimizing plugin's built-in configs, or enhancing plugin's features.

If some changes are happened, the refresh button will be appeared in the context float toolbar in the upper right corner of the editor. Click it to confirm to import, so changes of these custom config files will be applied.

IDE will take some time to reparse opened files in background, And please note that if the changes in the config files will result in the change of the indexing logic (for example, a new definition type is added, or a match condition for some definition type is changed), you may need to reindex the whole project (this may take several minutes), to make sure the plugin works properly, if in the situation that involves these changes.

Allowed values for gameType: stellaris, ck2, ck3, eu4, hoi4, ir, vic2, vic3 (or core for core config group) ↩︎ ↩︎ ↩︎