This page might be out of date. If you are after more recent information and have questions, please don't hesitate to ask in the #phantom-modding channel on BYG Discord.
¶ Overview
This document describes the changes to the modding support and adjacent systems of Phantom Brigade.
- The features can evolve over time based on test results and your feedback. APIs might change based on feedback, player-facing side effects necessitating design changes might be discovered, etc.
- Please make sure to share your thoughts in the #phantom-modding channel on BYG Discord. We recommend using Discord instead of the ingame Reporter to ensure the feedback isn't lost among player reports
¶ Update 1.3.3
Changes:
- Enabled Steam Workshop support.
- Players can subscribe to mods through the Steam Client or browsing the Workshop portal. Once Steam downloads the Workshop content, the game will detect and apply it on startup - like any other local mod.
- Improved the mod menu and metadata.yaml
- Screen layout reworked to support long mod names and descriptions without overflowing text
- Most metadata.yaml details are now inspectable right in the mod menu, in the tooltip located to the right of the mod menu
colorHuefield now applies accent color to mod details and mod entry in the listurlfield is now available for primary website. Specifying a link will make the details pane display the clickable link button to the right of mod name.- Embedded links are now supported in the mod description. Example (as seen on screenshot above):
[url=www.mymodwebsite.com][u]My other mods[/u][/url]. Use this if you need to display more than one link. - Improved error information. Mods with errors will display a formatted tooltip with them. If there are multiple errors, you can switch between them by pressing LMB or RMB on the error button.
- Fixed mod menu displaying malformed error tooltip before first click on the error button.
- Improved mod error messages for clarity. Absolute path to the mod is now trimmed. Exceptions are now trimmed to topmost part of the stack trace.
- Fixed the mod manager not loading directory based config overrides. Replaced config override code with a new ipmlementation from radionecrotic; made fallback behavior under GetDataTypeFromPath method optional for the new use case.
- Fixed base ModLink implementation searching for patches in an incorrect assembly (Assembly-CSharp defining base ModLink was used instead of the mod assembly). Added a virtual method OnLoad () that is not concerned with a Harmony instance, simplifying code mod setup when patching is not required.
- Added
modIndexLoadandmodIndexPreloadto ModLink to simplify debug logging. The former will contain the index of a given code mod among currently applied mods, while the latter will contain the index in the preload list, similar to what you see during preliminary loading logging or in the mod menu UI. - Adjusted ModLink base class for easier extensibility.
- Added
public virtual void OnLoadStart (): override if if you are not interested in Harmony patching and would just like to run some code using existing API, e.g. game event utility subscriptions - Added
public virtual void OnLoadEnd (): override if you are after code that doesn't require a Harmony patcher reference but must run after tag mapping, console command and metadata registration
- Added
- Fixed a bug in the config editing system leading to errors when accessing dictionaries.
- Fixed
CustomMemoryValuetype not being type hinted, preventing mods from serializing custom pilot data without additional attributes. - Fixed the part validation function bailing when socket input was null instead of iterating over every socket. Fixed the unit validation function not implementing the action validation interface. Added missing functions for entity instantiation in overworld.
- Added function callback on workshop project completion. This should allow workshop projects to trigger completely arbitrary side effects such as base memory changes, entity instantiation etc.
- Added support for triggering functions from base upgrades on load rather than on installation. This enables base upgrades with persistent effects in code mods: e.g. an upgrade unlocking a new mechanic via a static method will have that static method fire again every time a session with a given upgrade is loaded.
- Added a game event system that simplifies code modding, reducing the need to patch the game to subscribe to common events.
- Use
GameEventUtility.SubscribeToEventGeneralwith aSystem.Actioncallback for general events.- Available events: CampaignStart, CampaignExit, OverworldContextEnabled, OverworldContextDisabled ,OverworldWarStart, OverworldWarEnd, OverworldRetreatEnd, OverworldResupplyEnd, OverworldTimeMinute, OverworldTimeHour, OverworldTimeDay, BaseContextEnabled, BaseContextDisabled, CombatContextEnabled, CombatContextDisabled, CombatOutcome.
- Use
GameEventUtility.SubscribeToEventOnObjectwith aSystem.Action<object>callback for object specific events. You'll need to cast the received object to a specific type to make use of the objects in most contexts. Here are available events and suggested types to cast the receivedobjectinto:- ViewEntry (UI screen - CIView)
- ViewExit (UI screen - CIView)
- UnitStatsRefresh (Unit - PersistentEntity)
- BasePartInstalled (Blueprint - DataContainerBasePart)
- PilotAdded (Pilot - PersistentEntity)
- UnitBuilt (Unit - PersistentEntity)
- PartBuilt (Part - EquipmentEntity)
- SubsystemBuilt (Subsystem - EquipmentEntity)
- WorkshopBuildComplete (Processed project - DataBlockWorkshopProjectProcessed)
- Use
- Added support for side-loading custom maps. Mods must include a valid Area DB override with all the binary map data present. No special metadata.yaml flag required.
- Added support for side-loading custom 3D assets. Mods must include an AssetBundles folder and declare
includesAssetBundles: truein metadata.yaml.- In-game, you can use
mods.asset-preview-prefabcommand in mech customization screen to preview sideloaded prefabs. Specify mod name, then asset bundle name, then prefab name. - Once sideloaded,
ItemVisualprefabs are registered under{assetBundle.name}/{prefab.name}keys and are available for use in subsystem attachment collections, as seen on screenshot above. - Please refer to the documentation on how to update them.
- In-game, you can use
¶ Update 1.3
[ TODO ]
¶ Update 1.2
[ TODO ]
¶ Update 1.1
Changes:
- It is now possible to override the firing transform of a part without relying on transforms built into visual attachments. Declare
localTransformOverridevalue withpositionandrotationfields under theactivationfield of a primary weapon subsystem to take advantage of this feature:
- The attachment system supports placement relative to visual center instead of true model pivot. To enable this, set
centered: truein the attachment config, underkeyfield. This can be useful for 3D models that are offset from their true pivot, such as front parts of weapons. - There is a new set of console commands to help with kitbashing part visuals using the new attachment system. While it's not currently possible to implement a 3D editor for the attachment system, the console commands are an improvement over an iteration loop where you needed to restart the game to try every individual change to attachment transforms. The new console commands are intended to be used in the mech customization screen, with a selected socket:
cr.edit-system hardpointKey(for example,cr.edit-system external_arm_upper). The first command you need to enter. Selects a subsystem for editing. Grabs a unit and part from the mech customization screen, requires entering a specific hardpoint as an argument. ThehardpointKeyargument is necessary because not every visual-embedding subsystem is accessible through the customization screen - a part might be the lowest possible level a player would be able to select. Running the command “pins” the subsystem for further editing, providing context to other console commands in this set.
cr.edit-vis-key lookupKey visualKey(for example,cr.edit-vis-key 01 wpn_vis_set03_back_02). Adds an attachment with a given lookup key and visual model. If an attachment with a given lookup key already exists in the dictionary, replaces the visual model. Start with this command to register a new model or modify an existing attachment, then modify its placement. ThevisualKeyargument supports autocomplete - start typing to discover what's available!cr.edit-vis-remove lookupKey(for example,cr.edit-vis-remove 01). Remove an attachment with a specific key from a subsystem.cr.edit-vis-remove-all. Remove all attachments from a subsystem.cr.edit-vis-remove-all-legacy-visuals. Remove all legacy visuals from a subsystem ("visuals", not “attachments” in the subsystem config). Legacy visuals only define a name and can't be moved, centered, scaled or rotated, so most modded items with attachments might not require them. They might be useful to keep around in some rare cases, e.g. when making a version of an armor with attachments layered on top of legacy visuals.cr.edit-vis-centered lookupKey value(for examplecr.edit-vis-centered 01 false). Toggles whether a given attachment is placed relative to true pivot (iffalse) or relative to visual center (iftrue). Attachments added via the console command above default totrue.cr.edit-vis-pos lookupKey position(for example,cr.edit-vis-pos 01 (2, 0.5, -1.25)). Sets 3D position of a given attachment.cr.edit-vis-pos lookupKey axis position(for example,cr.edit-vis-pos 01 z -1.25). Sets 1D position of a given attachment on a given axis. Useful to avoid retyping the full vector when you want to adjust an axis in isolation.cr.edit-vis-pos-offset lookupKey position(for example,cr.edit-vis-pos-offset 01 (0.5, 0.5, 0)). Offsets 3D position of a given attachment. Useful for progressively modifying a position without remembering previous values, e.g. shifting an attachment 20cm up and 10cm right without remembering what preceding values were.cr.edit-vis-pos-offset lookupKey axis position(for example,cr.edit-vis-pos-offset 01 x 0.5). Offsets 1D position of a given attachment on a given axis. Similar to the above, but when you only need an offset on an isolated axis.cr.edit-vis-pos-offset-local lookupKey axis position(for example,cr.edit-vis-pos-offset-local 01 z 2.5). Offsets 1D position of a given attachment on a given local axis. Very useful for attachments that aren't aligned along any major axes. Allows you to express operations such as “shift a diagonally attached panel outward along its normal” without having to guess 2-3 offsets on separate axes.cr.edit-vis-rot *. A set of 4 commands similar to the 4 above, but for modifying attachment rotation (in Euler angles such as(-90, 180, 0)).cr.edit-vis-scale *. A set of 4 commands similar to the 4 above, but for modifying attachment scale.cr.edit-vis-match lookupKeyModified lookupKeySource(for example,cr.edit-vis-match 02 01). Matches position, rotation and scale of a first attachment to position, rotation and scale of a second attachment. Can be useful for pulling pieces together to begin local edits.cr.edit-vis-match-* lookupKeyModified lookupKeySource(for example,cr.edit-vis-match-pos 02 01). Matches a specific property (position, rotation, scale) between two attachments. Valid suffixes are-pos,-rot,-scale.cr.edit-vis-copy lookupKeySource lookupKeyCopy(for example,cr.edit-vis-copy 01_old 02_new). Creates a new attachment matched to the old attachment in terms of visuals, centering, position, rotation and scale. Very useful as a starting point in complex compositions: copy a certain precisely positioned piece, start modifying its visual, then start offsetting its position locally etc.cr.edit-vis-mirror lookupKey axis(for example,cr.edit-vis-mirror 01 x). Mirrors position, rotation and scale of an attachment on a given axis. Experimental, might not work for anything but X axis.cr.edit-vis-mirror-local lookupKey axis(for example,cr.edit-vis-mirror-local 01 x). Mirrors rotation and scale of an attachment on a given axis while leaving position unmodified. Experimental, might not work for anything but X axis.cr.edit-vis-dump. Dumps the description of the currently selected subsystem visuals to console and Windows clipboard. Final step of tweaking attachment visuals - from there, you can paste the generated text into a YAML file in your mod.cr.edit-vis-dump-key(for examplecr.edit-vis-dump-key 01). Dumps the description of one specific attachment to console. Not intended to be used for pasting into YAML, intended for quick reference and prioritizes readability.cr.edit-vis-save. Same as the above, but with an attempt to save the subsystem database to game data on top. This is not meant to be a way of implementing mods: we strongly recommend against direct game data modification, since it interferes with analytics, has issues with file permissions for some users and is rolled back by installation integrity checks. However, it can be useful in rare special cases where a modder might want to inspect a modified YAML file implementing the changes.
- New and modified console commands:
cr.scenario-escape- allows you to escape the combat encounter even if you're locked into it. stuns the enemy like a smoke charge, but without requiring one. a pattern I frequently get into is testing something in overworld and being attacked by a patrol before I remember to cheat in some smoke charges, which means I can't escape a fight. this solves it.ow.escalation-setnow works in briefing, refreshing a given scenario to an escalation value between 0 and 350. Note that the scenarios are not scaled by that exact 0-350 value and only by escalation level ("wanted" stars in the UI).ow.escalation-set-levelallows you to directly input a wanted level between 0-3, automatically setting precise 0-350 escalation value in the middle of desired range. Automatically resets scenario if in briefing.cm.teleport- allows you to teleport a selected unit in combat to speed up testing of scenarios that require long movement, testing of attacks at specific distances etc.cr.inv-generate-part- (might have been implemented right around 1.0 release, not sure if it's entirely new) allows you to verify how a given part is generated at provided 0-3 rating. It prints a full report, which is really handy for debugging part generation issues, confirming full spread of perks a part is eligible to roll etc. The game picks a random choice from all the possibilities for each hardpoint, so inspecting that is a great shortcut to inspecting 50+ generated parts manually.
- Added support for modifying melee shockwaves. The shockwaves are defined under Configs\DataDecomposed\Equipment\Shockwaves. Each shockwave describes a set of points moving through space, forming a line that collides with props, units and projectiles. Here is the annotated breakdown of the shockwave config and an animation to put the values into context:
- Added support for disabling threat rating based combat scaling system via simulation.yaml
unitScalingThreatBased(on by default). Threat rating is a value embedded into every overworld blueprint. It is increased by +20 for each escalation level in overworld. Threat rating based combat scaling system scans the generated combat scenario, calculates the threat rating of all encountered squads (unit groups), and activates if there is a decifit. It ranks up squads (from normal to veteran to elite, increasing equipment quality, level offset and unit count, depending on how a unit group is configured). When there are no more squads to rank up and a deficit remains, the system clones a random squad at grade 0. This system makes it easy to reuse the same scenario across entities with a different intended difficulty (e.g. base assault scenario will have different number and quality of units if played at an outpost with TR40 vs a base with TR100). However, this system might be undesirable for a tightly controlled experience with finely tuned squads and per-entity scenarios. - Added support for level based combat scaling system via simulation.yaml
unitScalingGradeBased(off by default). Should not be enabled together with TR scaling. An alternative to TR scaling that simply scales squads (unit groups) in scenarios proportionally to escalation level. Escalation 0: normal squads; 1: 50/50 normal/veteran squads; 2: 50/50 veteran/elite squads; 3: 100% elite squads. More predictable, ensures the player encounters exactly the squads defined in a scenario config. Requires additional scenarios per entity or embedded units defined directly on entities if the intended experience is supposed to differ between two entities pointing to the same scenario (for example, camps, outposts and bases should directly declare their garrisons outside of assault scenario if this is to be enabled, otherwise fights at all 3 entities will look the same). - Added support for a 7th mech socket (backpack). The new socket is intended for future content and not shipped in 1.1 but 1.1 includes some non-moddable dependencies blocking its implementation in mods, such as new game objects under the mech body prefab. The internal name for the new socket is
back. The new socket is not supported on any unit types except mechs. - Added an optional stat multiplier data component to combat unit entities. This is a dictionary that can multiply any stat of a unit, making it easy to create glass cannon units that are weaker than average or veteran units that are stronger than average, without having to create new equipment configs. The dictionary can be modified through following means:
statMultipliersdictionary on thecustomdata block of unit resolvers in unit group configs. Seecustom_patrol_swarm.yamlin UnitGroups database, where a large number of tanks is balanced by reducing their HP and barrier stats.cm.set-unit-stat-multiplierconsole command. Enables quick testing of altered unit stats, both for creatingcustomdata blocks and for testing possible permanent equipment balance changes.
- Added support for overworld entity blueprints defining combat units deployed at the beginning of combat or as reinforcements. A dependency for the updated patrol encounters, intended to be used for more entity/scenario pairs later on.
- Previously, scenarios rigidly define which unit roles show up in the fight and in what numbers, e.g. "this is a hard elimination scenario and it has 1 recon and 2 striker squads". This impacts variety - you might encounter 2 different patrol types but if the fight with them leads to hard elimination, the unit roles would be the same, with the only variation arising from map, spawns, biomes and fine details of generated equipment.
- The idea is to delete some of the defined squads from scenarios and shift the responsibility for defining "who's on the field" to overworld entity blueprints. This enables you to cheaply get unit variety without creating new scenarios. For example: Create a new patrol called a "armored column" and make it define 3 tank squads, create a new patrol called a "recon squad" and make it define 2 fast moving scout mech squad, create a new patrol called a "hunter team" and make it define 1 heavily armored sniper squad with preference to spawn far away from the player. Delete starting units from the elimination scenario that patrols qualify for. Fighting any of these patrols on exact same elimination scenario will now yield distinct starting units players must eliminate, in contrast with how the game worked before.
- Mod example: Delete all embedded units in the
generic_assaultscenario, modifybase,campandoutpostoverworld entity configs to feature different embedded squads. Seesquad_invader_patrol_*entities for examples. - The new field follows the data format for squads from combat scenarios and can be found under
scenarioUnitson Overworld/Blueprints configs.
- Expanded developer mode tooltips for overworld entities. Hover over new buttons in the bottom right corner of overworld UI while in developer mode to see extended entity blueprint information, embedded rewards information and memory information. Reward information was not accessible through developer UI before. Blueprint information now includes info on eligible maps and scenarios, as well as information about embedded units.
- Extended the reactive action system. Reactions now take a distance and angle from equipment (or an independently defined angle), and scan in an arc instead of a 360 degree circle. See the updated sentry turrets for more details. Makes reactions more interesting to play with and provides levers for additional unit types using reactive actions.
- Greatly extended scenario system capabilities
- Added support for running functions per unit filtered via a state condition. This allows expressing complex conditions/reactions scaling to arbitrary number of units, such as “when vehicles carrying explosives enter an objective zone, for each detected vehicle, spawn an explosion that applies X damage in Y range and reduces player score by -50”. Previously, it was only possible to express reactions on match to specific unit count or on match to arbitrary unit count, blocking large number of potential scenarios. [ TODO: Detail an example state ]
- Added support for unit targeted functions and implemented a large library of them. These include unit tagging, unit HP modification, unit relative special effects and AOE etc. [ TODO: Detail all functions in a separate article ]
- Greatly extended the number of supported global functions such as filtered unit modifications, external strikes etc. [ TODO: Detail all functions in a separate article ]
- Added support for non-prebaked unit spawns from state reactions. This unlocks entire classes of scenarios previously not implementable due to need to predict and prepare exact set of units needed for any possible path, such as defense objectives with looping spawns. [ TODO: Detail an example reaction config ]
- Added support for non-incrementing reaction states, allowing reactions to loop forever for as long as conditions are satisfied. Unlocks a large number of scenarios requiring recurring game state changes. [ TODO: Add an example config ]
- Added support for modulo based turn checks, allowing states to trigger every Nth turn, allowing for spacing out looped reactions.
- Added support for AI planning immediately after landing. Fixed AI being unable to path through destroyed units.
- Added an option to convert customized landing trajectories in
customdata block of spawned units to movement actions, allowing reinforcements in custom scenarios to arrive over ground and not from the air. - Added a new combat entity component (
AgentBehaviorDestination), new targeted function allowing its modification (CombatUnitDestinationChange) and 2 new AI behaviors making use of it (DefensiveDestinationandDumbDestination). Can be used to make AI units navigate to a specific point on the map based on global coords, map data or objectives, vs. circling player units as seen under standard behavior. - [ … ]
- Fixed the min/max mod version in metadata.yaml not being parsed if listed in
major.minorformat (1.1). Fixed min/max mod version being accepted in any other format thanmajor.minorormajor.minor.patch. - [ … ]
¶ Experimental update 1 (1.0.5-b5828E)
Changes:
- The mod menu appears when any mods are installed into the C:/Users/username/AppData/Local/PhantomBrigade/Mods folder. Creating mods.yaml manually and setting a special flag to enable mod support is no longer required.
- Updated the Harmony library to version 2.2.0.
- Replaced the log window with a popular SRDebugger asset. The new log window is available with Ctrl+Shift+F11 shortcut. It fits more information, performs better, sorts and filters messages better, makes it easier to inspect stack traces etc. Useful for troubleshooting mods and general debugging.
- Adjusted the structure of the
ModManagerclass to make patching mod loading code easier. Per-mod operations are now split into a separate method, so it is possible to affect mod loading right from within the very same loading pass (in contrast to old implementation where patching the loading method couldn't have an effect on subsequent mods until next load). See theLoadModmethod separated fromLoadMods. - Disabled alias generation in all YAML configs, re-saved all databases in updated format. The game remains backwards compatible with aliases, but none of the files included with the game should have references replacing duplicate values anymore. This should make editing colors, vectors, animation curves etc. much easier: no more aliases like
*o7taking place of actual values.
- Slightly simplified modding of additional interface-implementing classes such as overworld event, scenario or equipment functions. To allow usage of
!MyFunctionNametags in configs and enable the deserialization process to connect a tag to your new class, you can now modify the tag mapping collection. The collection can be retrieved viaUtilitiesYAML.GetTagMappingsand extended like so:tagMappings.Add ("!MyFunctionName", typeof(MyFunctionName)). - Slightly simplified modding in new Entitas ECS classes. Added
EntitasUtilities.InsertSystemInFeature<T>method to make registering new Entitas systems easier (e.g.InsertSystemInFeature<EquipmentSystems> (new MySystem)). Added `GameControllerState.GetSystems<T>` allowing fetching of a GameController state feature group, enabling the above and other similar usages. AddedGameController.GetInstanceto enable the above. - Weapon firing schedule can now be adjusted via the new data block exposing start time, end time and timing distribution exponent. This allows for more varied weapon designs with different firing timing, such as a minigun that starts slow and speeds up towards the end of an action or a sniper rifle that needs to be aimed for a while before firing.
- The new feature is available on activated weapon subsystems, under
activation/timingfield. - The
timeFromandtimeTofields are 0-1 floats expressing normalized time projectiles are fired in. E.g.timeFromof 0.5 would mean a weapon only starts firing past 50% of the attack duration. - The
exponentvalue is used to raise normalized projectile firing time to a given power. Consider a weapon with 5 projectiles. By default, they would have normalized firing times of 0, 0.25, 0.5, 0.75 and 1. Withexponent: 2, the firing times would turn to 0, 0.125, 0.25, 0.56 and 1 - the weapon would burst more projectiles early, and start shooting more slowly towards the end of the action. Withexponent: 0.5, the firing times would turn to 0, 0.5, 0.7, 0.86, 1 - the weapon would start slow and speed up towards the end. - We recommend avoiding exponent values below 0.5 and above 2 as the projectile spawning is constrained by framerate and compressing projectiles too tightly could lead to them spawning side by side.
- The new feature is available on activated weapon subsystems, under
- The splash damage system now supports all damage types (direct, concussive, stagger, heat), allowing for more varied explosive weapon designs.
- The part rating suffixes such as ++ are now moddable. Max part rating is no longer limited to 3 in the equipment generation system.
- Register text for
item_info_rating_{?}localization keys to override or provide new rating names. For example, moddingitem_info_rating_2would modify the “Uncommon” label and moddingitem_info_rating_4would register a new name for a rating above Rare. - Modify
equipmentRatingSuffixesdictionary under ui.yaml to override or provide new rating suffixes such as+++.
- Register text for
- Added support for transforming subsystem visuals. Previously, subsystem visuals could only be listed as a single string indicating which prefab to spawn. New attachment collection available on subsystems allows additionally defining position, rotation and scale of every spawned prefab. This unlocks kitbashing with existing assets, applying existing models in new contexts. Could help visually differentiate armor and weapons, especially as a stopgap without custom 3D model sideloading.
- To use the attachments, add entries to the
attachmentscollection under subsystem configs, as depicted above. You can declare any number of attachments. - Old
visualscollection is left in for backwards compatibility. Using it is equivalent to declaring an attachment at position 0,0,0 with rotation 0,0,0 and scale 1,1,1. The keys for the visuals and attachments are the same - please refer to the reference page.
- To use the attachments, add entries to the
- Added support for beam muzzle flash and impact effects (beams previously didn't spawn effects on contact or upon firing). The impact effect is set in the
beam.impactasset field similar to theimpactfield that's available underprojectiledata block. - Added support for recoloring visual effect assets referenced in the Subsystems database. Projectiles, muzzle flashes, beams and other effects of that kind can be adjusted from their default colors to visually differentiate a weapon type etc. This feature has a role similar to attachments: creating new effects is nontrivial and support for sideloading them might not arrive for some time, but reusing existing effects in new colors can be a useful stopgap. The following changes were made to the pooled asset data blocks:
- Removed
factionUsedfield from all pooled asset data blocks. It was redundant when presence of a value onkeyEnemyfield already indicates the asset needs to vary by faction. - This is extended to new color fields: all of them are added in pairs, and if an
*Enemyfield is left empty, the game assumes that assets of every faction should be colored using the value of base field. If base field is null as well, no color changes are applied. - There are two types of color modification: hue offset, and color override pairs. These are necessary based on different types of VFX art used in the game.
- Hue offset is a nullable object with a single 0-1 float field
finside. It is used on effects that consist of arbitrary number of colors, typically particle based effects, where directly defining a color or two is not nearly enough information to drive the full content of an effect. The change from the hue offset is akin to dragging a hue slider in software like Photoshop, with the 360 degree hue color wheel compressed into 0-1 range. If an original effect consists of a red flames and orange sparks, hue offset withf: 0.1will turn flames orange and sparks yellow (shift everything forward by 10% on the color wheel).f: 0.5will push the colors further forward, e.g. turn red to sky blue. - Hue offset is available through
hueOffsetandhueOffsetEnemyfields on the following asset data blocks:activation.local(muzzle attached firing effect) andactivation.root(unit attached firing effect)projectile.impact(hit effect on projectile collision) andprojectile.deactivation(effect on projectile expiring from distance or time)beam.impact(hit effect on beam collision)
- Color override pair is a nullable object with two
Colorproperties inside,colorFromandcolorTo. It is suited to VFX assets that are precisely controlled by a pair of colors. The pairs are available throughcolorOverrideandcolorOverrideEnemyfields on the following asset data blocks:projectile.body(asset attached to projectiles)beam.body(asset attached to beams)
- A simple mod copying an existing ballistic weapon that needs a unique color on every effect will have to use both of these data types. The simplest example would be:
- Set
projectile.body.key: fx_projectile_standard_blue, leavekeyEnemyempty - Set
projectile.body.colorOverrideto green and light green - Set
projectile.body.colorOverrideEnemyto purple and light purple - Set
activation.local.key: fx_muzzle_mg_heavy_blue, leavekeyEnemyempty - Set
activation.local.hueOffset.f: -0.2(shift blue towards green) andhueOffsetEnemy.f: 0.3(shift blue to purple) - The attached animation shows the result:
- Set
- Removed
- The function system used in events, scenarios, tutorials etc. has been extended to work with units in combat:
- The system can be used to execute completely arbitrary logic on events listed below. For example, it's possible to a weapon perks that heals the attacker when the weapon applies damage; or a subsystem retargeting a fired projectile to an a random enemy based on specific filters; or a perk that triggers a damaging explosion on pilot ejection etc.
- General part events: activation (start of a related equipment-enabled action), destruction. Provide access to the subsystem involved. To make a new function of this type, implement a class inheriting from
ISubsystemFunctionGeneral. - Targeted part events: weapon fired, weapon hit (damaging, critical). Provides access to the subsystem involved, position and direction of the event, target position or target unit, and projectile involved (if available). To make a new function of this type, implement a class inheriting from
ISubsystemFunctionTargeted. - Action part events: action start, action end. Provide access to the subsystem and action involved. To make a new function of this type, implement a class inheriting from
ISubsystemFunctionAction. - To enable the system, set
partEventsEnabled: truein simulation.yaml - To declare functions, use the new
functionslist in the Subsystems database configs. The field is a list to allow multiple hierarchy levels to declare their own functions: for example, a parent for a new weapon type might declare a special function that runs for every model in that type, and each model might add yet another function specific to its design. - Each entry in the
functionslist has 3 fields:general,targetedandaction, each of them a list of function invocations of a given type. See the first 3 bullet points for details on the role of the 3 types. - Each entry in the
general,targetedoractionlists has acontextslist field, which specifies exact events a given set of functions can be invoked under. For instance, you might want a certain special effect to spawn on part destruction, but not on part activation, so you'll liston_part_destructionundercontextsto achieve that. Full list:- General:
on_part_activation- called per subsystem within a part that is referenced by an equipment action, when an action starts - General:
on_part_destruction- called per subsystem within a part that is being destroyed - Targeted:
on_wpn_fired- called per subsystem within a weapon part firing a projectile (the unit being targeted will be passed in as an optional argument) - Targeted:
on_wpn_hit- called per subsystem within a weapon part responsible for a projectile that just hit another unit (the unit being hit will be passed in as an optional argument) - Targeted:
on_wpn_part_destruction- called per subsystem within a weapon part responsible for destroying another unit (the unit being destroyed will be passed in as an optional argument) - Action:
on_action_start- called per every subsystem in the unit when any action begins - Action:
on_action_end- called per every subsystem in the unit when any action ends - Looking forward to feedback on which additional events would be useful to add!
- General:
- Under context filter, you finally get a list of actual functions. These follow standard interface field syntax seen in other
functionsfields in contexts such as scenario or overworld event steps: each entry is preceded by a tag allowing the serialization system to learn which type it is dealing with. The built-in examples are limited to a few classes such asSubsystemFunctionLog,SubsystemSpawnEffectandSubsystemRetargetProjectiles, depicted below. These are provided as examples: the overall system is intended to be used with a code mod declaring additional freeform functions. - As mentioned above, make sure to register additional implementations of these interfaces with the tag mapping dictionary to allow loading of configs using them.
- Added support for
targetModevalue3on stat data blocks in subsystems. As a refresher:0is non-targeted (value gets added to stat sum in an item),1is additive targeted (add multiple of non-modified stat of a targeted item to stat sum in that item),2is multiplicative targeted (multiply the final stat of a targeted item by a given amount). New mode3is a targeted override: the declared value will entirely replace the final value of a targeted item. This is a fairly niche targeting mode, mostly useful for cases like setting shot count to exactly 1 or 2 in an exotic weapon perk, overriding mass for special NPCs etc. - Adjusted the data format in UnitStats configs. Added support for constraining a stat by value of another stat. Old functionality still present, just with fewer fields.
- Removed pairs of bools and values:
minPerPartLimit, minPerPart, maxPerPartLimit, maxPerPar, minPerUnitLimit, minPerUnit, maxPerUnitLimit, maxPerUnit, levelUsed, levelIncrease, multiplierUsed, multiplier. - Added nullable float fields:
minInPart, minInUnit, maxInPart, maxInUnit, increasePerLevel, scale - Added nullable string fields:
minFromStat, maxFromStat. The former is used inwpn_scatter_angle_moving, like so:minFromStat: wpn_scatter_angle.
- Removed pairs of bools and values:
- Added
DataMultiLinker.GetDataListmethod for iterating over databases without overhead of sorted dictionary iterators. - The 2D overlay system for pilot portraits has been reworked and returned to the game. 2D overlays are now applied in 3D space, enabling them to coexist with 3D pilots.
- Built-in assets for this system will include decorate frames complimenting 3D pilot views, but the system supports modding legacy style portraits. Every portrait texture supports alpha channel (make sure to use SuperPNG plugin in Photoshop to properly save alpha channel data into .png format).
- For a legacy portrait covering the 3D pilot, leave the alpha channel fully white (opaque).
- Pilot portrait textures are still added through Textures/UI/PilotPortraits folder. Make sure to enable texture loading in the mod metadata. Pilot portrait mods created in the past should be compatibe with this new system.
- To select an overlay texture, navigate to the pilot editor screen and use the overlay field at the bottom. Overlays can additionally be tinted and distorted a different amount through variants. Variant data is defined on Settings/pilots.yaml config, similarly to all other pilot customization assets.
- Player squads consisting of more than 5 units can now be spawned in without requiring map editing. All official maps only contain 5 spawn points per spawn group, which limits how many units per squad can be spawned in. A new fallback logic has been introduced when player spawn group is fully filled and more units remain in the queue: the game will search for a nearest unoccupied spawn group and continue spawning player units there. We're not sure using more than 4 player units is an enjoyable experience (the whole point of PB is asymmetric tactics with a small squad, with each turn requiring as little as possible time to plan), but supporting more player units has been one of the most popular modding feature requests for a while now, so we had to add support for this :)
- It is now possible to mitigate pilot, heat and stability damage.
- Stat
res_concussionvalues between 0 and 1 determine how much pilot damage is mitigated (e.g. unit total of 0.2 means 20% of pilot damage is skipped) - Stat
res_heatdoes the same for incoming heat from incendiary weapon hits - Stat
res_staggerdoes the same for hits from destabilizing weapons
- Stat
- Added support for overworld entity blueprints defining combat units deployed at the beginning of combat or as reinforcements. This a dependency for player facing 1.1 work (enabling different overworld units to trigger spawn different forces in combat within exact same scenario), but could be useful to some overworld mods.
- Overworld blueprint database configs have a new root level field
scenarioUnits. It is a list, with each entry containing three fields:step,tagsandunitGroups. unitGroupsfield is identical to the unit field under combat scenario steps or state reactions and allows defining squads (unit groups) that appear in combat, along with customizations and restrictions (such as minimum distance from the player). Embedded unit group type is not supported, but linked (directly referenced unit group DB keys) or filtered (tag filter for unit groups) are supported.tagsis a set of tags indicating where to use the defined units. most cases would use a single entry- startunder this field, indicating the units should appear on the field immediately, as part of the starting step of any combat scenario (all built-in scenarios are already tagged appropriately), but it's possible to define completely arbitrary tags and filter for them. Newtagsfield has been added to steps and state reaction data blocks to enable these checks.stepis a bool that determines whether a given unit description applies to scenario steps or scenario states. In most cases, where this feature would be used to inject units into the first step of a scenario, this would be set to true.
- Overworld blueprint database configs have a new root level field
- Added support for loading new UI sprites into the game.
- This is distinct from previously available support for loading portrait, overworld event and overworld entity UI textures. Most of Phantom Brigade UI is built from “sprites”: images combined into a single texture, enabling rendering of large parts of the UI in a single pass.
- Just like previously supported image types, sprites are loaded through the texture mod payload. The new folder used for the sprites is Textures\UI\Sprites.
- All files must use 8-bit RGBA PNG format. However, in contrast to other supported image types, filesize and resolution are not restricted. NPOT (non power of two) and non-square images are fully supported. Generally, it is not recommended to load a total of 1024x1024px worth of sprites, but average sprite matching existing UI totals around 32x32px.
- Built-in Photoshop PNG importer/exporter isn't great at handling alpha in PNG files, so we recommend the free SuperPNG plugin for creating appropriate PNG files if you're using Photoshop.
- It is possible to replace built-in textures by creating files matching built-in sprite names. If you'd like to register new sprites without overwriting existing content, make sure to reference the existing sprites in the UI debugging view.
- Added console commands to simplify UI view testing:
ui.view-list- lists all registered UI screens (views), printing GameObject path and exact type name. Type name is used fully or partially in the next 2 commands.ui.view-enter- attempts to enter a view with a type name matching the provided filter. Partially entering type names is supported, e.g.ui.view-enter CIViewInternalUIToolsandui.view-enter uitoolswill both work.ui.view-exit- attempts to exit a view with a type name matching the provided filter.
- Added console commands to simplify texture system debugging (e.g. verifying textures you modded were successfully loaded):
tex.print-groups- prints all supported texture groups, folder paths, file requirements and loaded textures (if any). Can be constrained with optional group name filter argument, e.g.tex.print-groups overworldwill print only 2 overworld-related groups.tex.load- re-loads the texture database. Can be useful for quickly testing images via direct editing of the StreamingAssets install folder before attempting to create a mod.
- Added UI atlas debugging view. Can be invoked via
ui.view-enter uitools, as seen in the example above.- Displays all UI sprites registered in the game. You can advance left/right through with the arrow buttons to jump -10, -1, +1, +10 sprites in the list. You can also use the list on the left of the arrow buttons to select a nearby sprite by name. The panel on the right displays how a sprite fits into the full atlas texture.
- Useful for learning which images can be used in configs (the game has a large number of
string iconfields in different configs which require entering a valid sprite name), confirming internal data such as sprite resolution, verifying whether modded sprites were correctly loaded, debugging issues with sprite metadata etc.
- Added a utility for click callbacks in text, making it easier to set up simple text based UIs:
- First, create a new object with
UILabelcomponent (underCIViewLoader.insanchor objects), or use an existingUILabelcomponent (e.g. from one ofCIView*.insobjects). Ensure the same object has aCollidercomponent attached and is on theUIlayer (5). - Call
myLabel.RegisterURLCallback ("myCallbackKey", new UICallback (MyVoidMethod));to register an alias and associated callback void method. - Edit
myLabel.textto insert the alias into text, allowing the registered callback to trigger on clicks. For example,myLabel.text = “This is static text. [url=myCallbackKey]This is clickable text.[/url]”. - While this isn't as powerful as using
CIButtoncomponents, it is a very easy way to set up a basic interactive UI, especially when modding in a new UI view from code.UICallbackclass supports many function signatures and fits most use cases needed in UIs. Check theCIViewInternalUIToolsclass (the UI debug view described above) for an example of using this: the nearest sprite name list on the left is a single label with per-line click callbacks.
- First, create a new object with
Fixes:
- Integrated the improvements to the config editing system from EchKode. These include support for instantiating specific inheriting or interface implementing value types into ambiguous fields, an operator for setting value to null, fixes to edge cases etc. Improved handling of different field types, restructured code for easier maintenance and extension.
- Fixed the min/max version checks in the modding system. Previously, max version constraint triggered a check of the min version requirement, making the entire version restriction feature non-functional, which was especially problematic for code mods.
- Fixed the additive targeted stats using unleveled values of the targeted subsystem. This made subsystems like plating useless at higher levels.
- Fixed the missile trails failing to appear for a considerable distance after launch position.
- Fixed the damage events not using the parent component in all cases. This blocked damage attribution in some cases, which could block certain mods trying to implement e.g. extended combat log UI.
- Fixed the data types not registered under
PhantomBrigade.Datanamespace not being moddable through the config editing system. - Fix the inheritance of subsystem visuals being inverted, resulting in parents overriding child data instead of intended opposite behavior. This blocked subsystem mods with visual inheritance.
- Fixed the spawn cheats failing to process some subsystems due to an outdated blocklist. This made testing of some subsystems more time consuming, requiring save editing.
- Fixed the guided weapons directing projectiles towards targets instead of along the normal of the firing transform, making off bore weapons impossible. A missile launcher fired up still had missiles exiting the transform in target direction before this fix, etc.
- Fixed the moving scatter stat not being clamped by the idle scatter stat.
¶ Under investigation
The following features are under investigation and might require some time to realize. We're hoping they can be delivered but can't commit to a specific window for the time being.
- Steam Workshop support to improve mod discovery and delivery.
- Additional documentation to help mod complex configs and systems.
- Support for loading visual assets, to enable modding unit visuals (armor, weapons, etc.), props & effects.
- Visual level editor and support for loading custom levels.
