Struct GroupFormation 

pub struct GroupFormation { /* private fields */ }

A single formation definition specifying how units should be arranged.

Each formation includes AI usage criteria, unit requirements, and a set of formation blocks that define where different unit types should be positioned.

Implementations

impl GroupFormation

pub fn add_container( &mut self, parent_id: Option<u32>, position: (f32, f32), format: GroupFormationsFormat, ) -> Result<u32>

Adds a container with the defaults used by vanilla files at the end of the formation.

Arguments

• parent_id - Block to position the container relative to, or None for an absolute container.
• position - Offset from the parent for relative containers, or position for absolute ones.
• format - Format of the file, to create a valid entity preference.

Returns

The id of the new block.

Errors

Returns an error if the parent doesn’t exist.

pub fn add_span(&mut self, member_ids: &[u32]) -> Result<u32>

Adds a span over the provided blocks at the end of the formation.

Arguments

• member_ids - Blocks covered by the span.

Returns

The id of the new block.

Errors

Returns an error if any of the members doesn’t exist.

pub fn set_span_members( &mut self, span_id: u32, member_ids: &[u32], ) -> Result<()>

Replaces the members of a span.

Arguments

• span_id - The span to edit.
• member_ids - New blocks covered by the span.

Errors

Returns an error if a block doesn’t exist, the edited block isn’t a span, or a member depends on the span.

pub fn reparent( &mut self, block_id: u32, parent_id: Option<u32>, params: &LayoutParams, ) -> Result<()>

Changes the parent of a container, keeping its simulated position when possible.

Arguments

• block_id - The container to edit.
• parent_id - The new parent, or None to turn it into an absolute container.
• params - The simulated deployment used to keep the container in place.

Errors

Returns an error if a block doesn’t exist, the edited block is a span, or the new parent depends on the edited block.

pub fn move_block( &mut self, block_id: u32, center: (f32, f32), grid_step: f32, params: &LayoutParams, ) -> Result<()>

Moves a container so its simulated center lands on the target, snapping its offset or position to a grid.

Arguments

• block_id - The container to move.
• center - Target position of the container’s center.
• grid_step - Size of the grid to snap to, or 0 to not snap.
• params - The simulated deployment used to compute the offset.

Errors

Returns an error if the block doesn’t exist, is a span, or it or its parent can’t be positioned.

pub fn move_blocks( &mut self, block_ids: &[u32], delta: (f32, f32), grid_step: f32, params: &LayoutParams, ) -> Result<()>

Moves several blocks by the same distance, snapping their offsets or positions to a grid.

Spans are moved by moving their members. Blocks that depend on another moved block already move with it, so they’re left untouched.

Arguments

• block_ids - The blocks to move.
• delta - Distance to move them.
• grid_step - Size of the grid to snap to, or 0 to not snap.
• params - The simulated deployment used to compute the offsets.

Errors

Returns an error if a block doesn’t exist, or a moved block or its parent can’t be positioned.

pub fn delete_blocks( &mut self, block_ids: &[u32], params: &LayoutParams, ) -> Result<()>

Deletes blocks, re-attaching the containers positioned relative to them to their closest surviving ancestor.

Spans left without members are deleted too. Containers left without ancestors become absolute.

Arguments

• block_ids - The blocks to delete.
• params - The simulated deployment used to keep re-attached containers in place.

Errors

Returns an error if any of the blocks doesn’t exist.

pub fn delete_subtree( &mut self, block_id: u32, params: &LayoutParams, ) -> Result<()>

Deletes a block, all the containers positioned relative to it, recursively, and the spans left without members.

Arguments

• block_id - The root of the subtree to delete.
• params - The simulated deployment used to keep re-attached containers in place.

Errors

Returns an error if the block doesn’t exist.

pub fn sort_blocks(&mut self)

Reorders the blocks so each one comes after the blocks it depends on.

Blocks keep their current order when possible, and blocks in reference cycles are moved to the end.

pub fn depends_on(&self, block_id: u32, target_id: u32) -> bool

Returns if a block is the target, or depends on it directly or through other blocks.

Arguments

• block_id - The block to check.
• target_id - The block that may be depended on.

Returns

true if making the target depend on the block would create a reference cycle.

impl GroupFormation

pub fn layout(&self, params: &LayoutParams) -> HashMap<u32, LayoutRect>

Computes the simulated position and size of every block of the formation.

Arguments

• params - The simulated deployment to use.

Returns

The rect of each block, by block id. Blocks that can’t be placed due to missing references, reference cycles or empty spans are left out.

impl GroupFormation

pub fn validate(&self) -> Vec<ValidationIssue>

Checks the blocks of this formation for consistency problems.

Returns

A list of the issues found, in block order.

impl GroupFormation

pub fn name(&self) -> &String

Name identifier for this formation.

pub fn ai_priority(&self) -> &f32

AI priority value for selecting this formation (higher = more preferred).

pub fn ai_purpose(&self) -> &AIPurpose

Bitflags indicating when this formation should be used (attack, defend, naval, etc.).

pub fn uk_2(&self) -> &u32

Unknown field, present in Troy and later.

pub fn min_unit_category_percentage(&self) -> &Vec<MinUnitCategoryPercentage>

Minimum percentage requirements for unit categories in this formation.

pub fn ai_supported_subcultures(&self) -> &Vec<String>

List of supported subcultures (introduced in Rome 2).

If non-empty, this formation is only available to armies from these subcultures.

pub fn ai_supported_factions(&self) -> &Vec<String>

List of supported factions (introduced in Rome 2).

If non-empty, this formation is only available to armies from these factions.

pub fn group_formation_blocks(&self) -> &Vec<GroupFormationBlock>

Formation blocks defining unit positions and arrangements.

impl GroupFormation

pub fn name_mut(&mut self) -> &mut String

Name identifier for this formation.

pub fn ai_priority_mut(&mut self) -> &mut f32

AI priority value for selecting this formation (higher = more preferred).

pub fn ai_purpose_mut(&mut self) -> &mut AIPurpose

Bitflags indicating when this formation should be used (attack, defend, naval, etc.).

pub fn uk_2_mut(&mut self) -> &mut u32

Unknown field, present in Troy and later.

pub fn min_unit_category_percentage_mut( &mut self, ) -> &mut Vec<MinUnitCategoryPercentage>

Minimum percentage requirements for unit categories in this formation.

pub fn ai_supported_subcultures_mut(&mut self) -> &mut Vec<String>

List of supported subcultures (introduced in Rome 2).

If non-empty, this formation is only available to armies from these subcultures.

pub fn ai_supported_factions_mut(&mut self) -> &mut Vec<String>

List of supported factions (introduced in Rome 2).

If non-empty, this formation is only available to armies from these factions.

pub fn group_formation_blocks_mut(&mut self) -> &mut Vec<GroupFormationBlock>

Formation blocks defining unit positions and arrangements.

impl GroupFormation

pub fn set_name(&mut self, val: String) -> &mut Self

Name identifier for this formation.

pub fn set_ai_priority(&mut self, val: f32) -> &mut Self

AI priority value for selecting this formation (higher = more preferred).

pub fn set_ai_purpose(&mut self, val: AIPurpose) -> &mut Self

Bitflags indicating when this formation should be used (attack, defend, naval, etc.).

pub fn set_uk_2(&mut self, val: u32) -> &mut Self

Unknown field, present in Troy and later.

pub fn set_min_unit_category_percentage( &mut self, val: Vec<MinUnitCategoryPercentage>, ) -> &mut Self

Minimum percentage requirements for unit categories in this formation.

pub fn set_ai_supported_subcultures(&mut self, val: Vec<String>) -> &mut Self

List of supported subcultures (introduced in Rome 2).

If non-empty, this formation is only available to armies from these subcultures.

pub fn set_ai_supported_factions(&mut self, val: Vec<String>) -> &mut Self

List of supported factions (introduced in Rome 2).

If non-empty, this formation is only available to armies from these factions.

pub fn set_group_formation_blocks( &mut self, val: Vec<GroupFormationBlock>, ) -> &mut Self

Formation blocks defining unit positions and arrangements.

impl GroupFormation

pub fn new(name: &str, format: GroupFormationsFormat) -> Self

Creates an empty formation valid for the provided format.

Arguments

• name - Name of the new formation.
• format - Format of the file the formation will belong to.

Returns

A formation with no blocks and the AI purpose version expected by the format.

Trait Implementations

impl Clone for GroupFormation

fn clone(&self) -> GroupFormation

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for GroupFormation

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for GroupFormation

fn default() -> GroupFormation

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for GroupFormation

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl PartialEq for GroupFormation

fn eq(&self, other: &GroupFormation) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl Serialize for GroupFormation

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for GroupFormation