编辑“Coat of arms modding”

{{Version|timeless}}
'''Coat of arms''' are images used on shields and flags to identify titles, dynasties, and houses.

They are scripted in ''game\common\coat_of_arms\coat_of_arms''. 

They follow the basic scripting syntax of:

<syntaxhighlight>
coat_of_arms_name = {
    keyword1 = value1
    keyword2 = value2
    ...
}
</syntaxhighlight>

== Valid Keywords ==
{| class="wikitable" 
|-
! colspan="3" | Keyword
! Comment
! Example
|-
| colspan="3" | <syntaxhighlight>parent</syntaxhighlight>
| Used for inheritance, read more below.
| <syntaxhighlight>parent = k_england</syntaxhighlight>
|-
| colspan="3" | <syntaxhighlight>pattern</syntaxhighlight>
| The path to the file for the background pattern (usually located in ''game/gfx/coat_of_arms/patterns/'').
| <syntaxhighlight>pattern = "pattern_vertical_split_01"</syntaxhighlight>
|-
| colspan="3" | <syntaxhighlight>color1
color2
color3
color4
color5</syntaxhighlight>
| Specifies a color, to be used in the pattern or as a color reference in colored_emblems.<br /><br />Usually refers to a color defined in ''common/named_colors''.<br /><br />Can also define RGB, Hexadecimal, and HSV.
| <syntaxhighlight>color1 = "white"
color2 = hsv { 1.0 1.0 1.0 }
color3 = hsv360 { 360 100 100 }
color4 = hex { ffffff }
color5 = rgb { 255 255 255 }</syntaxhighlight>
|-
| rowspan="7" | <syntaxhighlight>textured_emblem</syntaxhighlight>
| colspan="2" | ---
| Multiple textured emblems can be specified. Each is itself a scripting object with the following valid keywords:
| ---
|-
| colspan="2" | <syntaxhighlight>texture</syntaxhighlight>
| The path to the file for the emblem (usually located in ''game/gfx/coat_of_arms/textured_emblems/'').
| <syntaxhighlight>texture = "te_griffin_01.dds"</syntaxhighlight>
|-
| colspan="2" | <syntaxhighlight>mask</syntaxhighlight>
| The coat of arms' background pattern can be used as a clipping mask for emblems.
| <syntaxhighlight>mask = { 1 3 }</syntaxhighlight>
|-
| rowspan="4" | <syntaxhighlight>instance</syntaxhighlight>
| <syntaxhighlight>scale</syntaxhighlight>
| Given as a 2-dim float, has default value { 1.0 1.0 }
| rowspan="4" | <syntaxhighlight>instance = { 
	scale = { 0.5 0.5 }  
	position = { 0.75 0.75 } 
	rotation = 45
	depth = 5  
}</syntaxhighlight>
|-
| <syntaxhighlight>position</syntaxhighlight>
| Given as a 2-dim float, has default value { 0.0 0.0 }
|-
| <syntaxhighlight>rotation</syntaxhighlight>
| Given as float value, has default value 0.0
|-
| <syntaxhighlight>depth</syntaxhighlight>
| Used to order rendering, given as float value with default of 0.0
|-
| rowspan="6" | <syntaxhighlight>colored_emblem</syntaxhighlight>
| colspan="2" | ---
| Multiple colored emblems can be specified. Each is itself a scripting object with the following keywords:
| ---
|-
| colspan="2" | <syntaxhighlight>texture</syntaxhighlight>
| The path to the file for the emblem (usually located in ''game/gfx/coat_of_arms/colored_emblems/'').
| <syntaxhighlight>texture = "ce_crown.tga"</syntaxhighlight>
|-
| colspan="2" | "
| All fields from textured_emblem are valid
| ---
|-
| colspan="2" | <syntaxhighlight>color1</syntaxhighlight>
| defines the base colour of the emblem
| rowspan="3" | <syntaxhighlight>color1 = color2
color2 = "white"
#color3 = hsv360 { 360 50 50 }</syntaxhighlight>
|-
| colspan="2" | <syntaxhighlight>color2</syntaxhighlight>
| defines the secondary color of the emblem (the Green channel in the texture)
|-
| colspan="2" | <syntaxhighlight>color3</syntaxhighlight>
| currently unavailable, will default to white
|-
| rowspan="4" | <syntaxhighlight>sub</syntaxhighlight>
| colspan="2" | ---
| Multiple subs can be specified, each is itself a complete coat of arms scripting object, allowing all fields except another sub, i.e. no sub nesting.
| ---
|-
| rowspan="3" | <syntaxhighlight>instance</syntaxhighlight>
| <syntaxhighlight>scale</syntaxhighlight>
| Given as a 2-dim float, has default value { 1.0 1.0 }
| ---
|-
| <syntaxhighlight>offset</syntaxhighlight>
| Given as a 2-dim float, has default value { 0.0 0.0 }
| ---
|-
| <syntaxhighlight>depth</syntaxhighlight>
| Used to order rendering, given as float value with default of 0.0
| ---
|}

== Examples ==
Here follows a few examples with their corresponding coat of arms.
<syntaxhighlight>
flag_with_emblem = {
    pattern = "pattern_vertical_split_01"
    color1 = "lemon_yellow"
    color2 = "sky_blue"
 
    textured_emblem = {
        texture = "te_griffin_01"
    }
}
</syntaxhighlight>
<syntaxhighlight>
flag_with_culled_emblem = {
    pattern = "pattern_vertical_split_01"
    color1 = "lemon_yellow"
    color2 = "sky_blue"
 
    textured_emblem = {
        texture = "te_griffin_01"
        mask = { 1 }
    }
}
</syntaxhighlight>
<syntaxhighlight>
two_emblems_scaled_and_positioned = {
    pattern = "pattern_vertical_split_01"
    color1 = "lemon_yellow"
    color2 = "sky_blue"
 
    textured_emblem = {
        texture = "te_griffin_01"
        instance = { position = { 0.75 0.75 } scale = { 0.5 0.5 }  }
        instance = { position = { 0.75 0.25 } scale = { 0.5 0.5 }  }
    }
}
</syntaxhighlight>

[[File:Emblem examples.png]]

== Inheritance and subs ==

This section is largely dedicated towards inheritance, but to facilitate that discussion, first two points on subs:

The first "base coat of arms" is an implicit sub:
<syntaxhighlight>
a = {
    pattern = "pattern_solid.tga"
    color1 = "blue"
    sub = { }
}
# the above is equal to:
b = {
    sub = {
        pattern = "pattern_solid.tga"
        color1 = "blue"
    }
    sub = { }
}
</syntaxhighlight>

Each instance field (coat of arms instances, not emblem instances) is transformed into a separate sub:
<syntaxhighlight>
a = {
    color1 = "blue"
    instance = { offset = { 0 0 } } # A
    instance = { offset = { 1 0 } } # B
    sub {
        color1 = "red"
        instance = { offset= { 0 1 } } # C
        instance = { offset = { 1 1 } } # D
    }
}
# the above is equal to:
b = {
    sub = {
        color1 = "blue"
        instance = { offset = { 0 0 } } # A
    }
    sub = {
        color1 = "blue"
        instance = { offset = { 1 0 } } # B
    }
    sub {
        color1 = "red"
        instance = { offset = { 0 1 } } # C
    }
    sub {
        color1 = "red"
        instance = { offset = { 1 1 } } # D
    }
}
</syntaxhighlight>

With that out of the way, let's dive into inheritance.

Inheritance is achieved through the parent keyword. It basically says "Fetch the coat of arms given as value, and use it to populate any fields not explicitly set".

Example:
<syntaxhighlight>
daddy = {
    pattern = "pattern_checkers_01.tga"
    color1 = "burned_red"
    color2 = "mid_grey"
    colored_emblem = {
        texture = "ce_angel.dds"
        color1 = "rust_brown"
        color2 = "rust_brown"
    }
}
 
child = {
    parent = "daddy"
    pattern = "pattern_checkers_diagonal_01.tga"
    color1 = "mint_green"
    # >color2 = "mid_grey"<        inherited
    # >colored_emblem = { ... }<   inherited
}
</syntaxhighlight>

When it comes to emblems the inheritance is "all or nothing": if at least one emblem (of any type) is specified, no emblems are inherited, but if no emblem is specified, all the parent's emblems are inherited.

The inheritance rules become slightly more complicated once subs are involved. The two guiding rules are:

When a parent is specified, all values are fetched from its first sub (which many times will be an "implicit" sub).
If a sub doesn't specify a parent it will piggyback on the parent of its first sub. However, in this case all values will be fetched from the corresponding sub in the parent. Setting parent = "none" disables this automatic inheritance.
Example:
<syntaxhighlight>
daddy = {
    pattern = "pattern_solid.tga"
    sub = { }
    sub = { }
}
 
child = {
    parent = "daddy"
    # this implicit sub inherits from the implicit sub in daddy
    sub = {
        # Since no parent is specified this sub will piggyback on >parent = "daddy"< and inherit from the second sub of "daddy".
    }
    sub = {
        parent = "other_coa"
        # since parent is specified explicitly this will inherit from first sub of "other_coa"
    }
}
</syntaxhighlight>

Inheritance chains ("deep inheritance") is resolved in a bottom up manner. Users must take care not to create inheritance loops.

<syntaxhighlight>
grand_dad = {
    pattern = "pattern_solid.tga"
    sub = { }
}
 
daddy = {
    parent = "grand_dad"
    # >pattern = "pattern_solid.tga"< inherited
    color1 = "blue"
    # >sub = { }< inherited
}
 
child = {
    parent = "daddy"
    # >pattern = "pattern_solid.tga"< inherited
    # >color1 = "blue"< inherited
    sub = {
        # this inherits from the second sub in daddy
    }
    sub = {
        # since daddy only has 2 subs, this has no parent
    }
}
</syntaxhighlight>

And finally, a real example:
<syntaxhighlight>
k_england_and_france = {
    sub = {
        parent = "k_france"  # defined elsewhere
        instance = { offset = { 0.0 0.0 } scale = { 0.5 0.5 }  } # top left
        instance = { offset = { 0.5 0.5 } scale = { 0.5 0.5 }  } # bottom right
    }
    sub = {
        parent = "k_england"  # defined elsewhere
        instance = { offset = { 0.5 0.0 } scale = { 0.5 0.5 }  } # top right
        instance = { offset = { 0.0 0.5 } scale = { 0.5 0.5 }  } # bottom left
    }
}
</syntaxhighlight>

{{Modding navbox}}
[[Category:模组制作]]