JSON Kungfu Made in CHINA (Unique tutorial for slide and layout)

The best tutorial about JSON in Steam and in hawkaoe.net

Welcome all AOE2DE lovers to translate it into German, Russian, French, Spanish, it is my pleasure.
Please send the translated version to my email [e-mail], thanks for your cooperation!


JSON Kungfu Made in CHINA
1.9
First author: cly806
Second author: newtonerdai
Compilation：cly806
---Hawkaoe Forum production---



Original release link: http://www.hawkaoe.net/bbs/thread-146341-1-1.html
Update Date:2021.5.28

Catalog

Editorial

Warm Tips

I Slide json Full Decryption

I-01 About JSON Annotation Issues and Basic Syntax
I-02 About the Construction of Slide json
I-03 SlideBackgroundImage
I-04 SlideImageSequence
I-05 Slideshow Narration Voice (Sound)
I-06 Slide Duration and Text Fade Out Time (Duration; TextFadeDuration)
I-07 Image Controls (ImageRect)
I-08 Text Contents (String)
I-09 TextRect Controls (TextRect)

II Layout json Great Exploration

II-01 Overview of layout.json
II-02 Custom Materials & Scenarios Selection Backgrounds (UserMaterials)
II-03 Main-title Label (TitleLabel)
II-04 Custom Styles for Main Header Box
II-05 Sub-title Box (LobbyBox)
II-06 Chapter Icon Button under the Main Component (Button, Image)
II-07 Questions about ZPlane Disabling
II-08 Chapter Icon Button Four States (Disabled, Normal, Hover, Pressed)
II-09 Sub-part 1: Scenarios Title Position & Black Translucent (CampaignTitle)
II-10 Sub-part 2: White Curve Border (ClippingOverride)
II-11 Sub-part 3: Difficulty Sword Setting (Level)
II-12 Sub-part 4: Scenarios Text Box Color & Font Size & Text Content Setting
II-13 Additional Part 1: Hover Text Box Battle Category Label (DataValue)
II-14 Additional Part 2: Hover Text Box (Help)
II-15 Additional part 3: Button Pressed Sound (ClickSound)
II-16 Text Arrow Widget (Next Indicator)

III Appendix

III-1 Appendix 1: Compiling of info.json
III-2 Appendix 2: Standard Process of HD Scenarios to DE
III-3 Appendix 3: Suggestions for Making Mod Covers Images
III-4 Appendix 4: Various Portals and Reference Documents
III-5 Appendix 5: Postscript & Acknowledgements

Editorial

In AOE2DE era, JSON as an indispensable accessory of a campaign, determine the integrity of a campaign, because it is different from the HD version of that simple JSON, the performance of a variety of forms, so it is also one of the major focus of the study of the campaign maker. After several months of dismantling the official documents and discoveries to explore, we finally found most of the JSON effect in a variety of ways to achieve. Of course, there are a small number of the author's technical level failed to explore, I hope to throw a brick to draw jade, so that more knowledgeable people continue to explore more black technology, creating a new era of JSON production.

Warm Tips

JSON Kungfu Made in CHINA is how to get started quickly to familiarize people with the production of slide json and layout json, so only the part of the effect to be detailed, the rest of the parts are omitted, aspiring to study the campaign producers can view sample files to explore on their own, not much to say here.
We recommend using various text editors, such as NotePad++, UltraEdit, VsCode, etc., with syntax highlighting, indented tree diagrams, etc., for easy reading and understanding.

Catalog

Editorial

Warm Tips

I Slide json Full Decryption

I-01 About JSON Annotation Issues and Basic Syntax
I-02 About the Construction of Slide json
I-03 SlideBackgroundImage
I-04 SlideImageSequence
I-05 Slideshow Narration Voice (Sound)
I-06 Slide Duration and Text Fade Out Time (Duration; TextFadeDuration)
I-07 Image Controls (ImageRect)
I-08 Text Contents (String)
I-09 TextRect Controls (TextRect)

II Layout json Great Exploration

II-01 Overview of layout.json
II-02 Custom Materials & Scenarios Selection Backgrounds (UserMaterials)
II-03 Main-title Label (TitleLabel)
II-04 Custom Styles for Main Header Box
II-05 Sub-title Box (LobbyBox)
II-06 Chapter Icon Button under the Main Component (Button, Image)
II-07 Questions about ZPlane Disabling
II-08 Chapter Icon Button Four States (Disabled, Normal, Hover, Pressed)
II-09 Sub-part 1: Scenarios Title Position & Black Translucent (CampaignTitle)
II-10 Sub-part 2: White Curve Border (ClippingOverride)
II-11 Sub-part 3: Difficulty Sword Setting (Level)
II-12 Sub-part 4: Scenarios Text Box Color & Font Size & Text Content Setting
II-13 Additional Part 1: Hover Text Box Battle Category Label (DataValue)
II-14 Additional Part 2: Hover Text Box (Help)
II-15 Additional part 3: Button Pressed Sound (ClickSound)
II-16 Text Arrow Widget (Next Indicator)

III Appendix

III-1 Appendix 1: Compiling of info.json
III-2 Appendix 2: Standard Process of HD Scenarios to DE
III-3 Appendix 3: Suggestions for Making Mod Covers Images
III-4 Appendix 4: Various Portals and Reference Documents
III-5 Appendix 5: Postscript & Acknowledgements

I Slide json Full Decryption

I-01 About JSON Annotation Issues and Basic Syntax

I-01 About JSON Annotation Issues and Basic Syntax

The problem that JSON cannot be annotated has been around for a long time, but here we tell you that you can actually use annotations.
The syntax of JSON is a bit like that of a dictionary in Python (in short, a key-value pair [Key-Value]). In general, there are two ways to annotate JSON, and you can choose according to your needs.
JSON features: data is separated by commas, curly brackets are used to save objects, middle brackets are used to save arrays, and the last attribute cannot be comma-separated.

①"//": "annotated contents"【Strength: Versatility and neatness】
②" prefix character + variable name ": " annotated contents "
【Strength: Annotated variables correspond one-to-one】 (prefix character such as #? _)
Exp: "?Sound":" annotated contents "
*JSON syntax is that curly brackets must be separated from curly brackets by commas. (You cannot add a comma if there is only one or at the end of the curly brackets)
**Note: If you use syntactically incorrect annotation method will cause JSON cannot be used, so you must check the syntax.
***Common syntax errors:(missing/multi {} or,) Be sure to check carefully, generally each key-value pair should be followed by a comma, (special ones will be specified) only use the symbols inside the English input method.
****Any syntax error in JSON will cause a JSON error and the background will disappear.
*****"Type" designation error will lead to loading the level selection interface completely black screen or even stuck, "alignment", "TextAnchor" behind the alignment spelling error will also lead to a black screen, can only restart the game to solve.

Editor's Note:

1. To test the slide or layout, you must aoe2campaign and two json with the same name (_layout count suffix), otherwise there will be no effect.
2. All materials must be imported before starting the game exe, otherwise there will be a mosaic situation, which can be solved by restarting the game or importing the MOD, it is best to avoid.
3.To deal with JSON syntax error verification problem you can use vscode's automatic check or use the website http://bejson.com/explore/index_new/ to check. If the default interface or slideshow cannot be modified, it can be said that 99% are syntax errors, please check again carefully and patiently.

【This section must be read, if you don't read it, you are responsible for the consequences. 】

I-02 About the Construction of Slide json

I-02 About the Construction of Slide json

For the slide json, the format is "campaignname.json"
It consists of two parts, the in-slide IntroSequence and the out-slide OutroSequence(both parts are almost identical). Each part is divided into the following main sub-modules.

○1 SlideBackgroundImage
○2 SlideImageSequence
○3 Slideshow narration voice (Sound)
○4 Slide duration and text fade out time (Duration; TextFadeDuration)
○5 Image controls (ImageRect)
○6 Text contents (String)
○7 TextRect controls (TextRect)

The following is a detailed description of the relevant points in modules in the order of writing. First of all, you must ensure that the type is SlideShow "Type": "SlideShow",

I-03 SlideBackgroundImage

I-03 SlideBackgroundImage

Relative position in json:

General format is：
"SlideBackgroundImage":"textures/campaign/CampaignCatalogName/CampaignName _background.dds",

*其中为了方便大家更好找到战役目录,特罗列于下:
Acam1-4: TariqIbnZiyad, Sundjata, Francisco, Yodit
Cam0-5: The Art of War, WilliamWallace, Joan, Saladin, GenghisKhan, Barbarossa
Fcam1-7: Alaric, Dracula, Bari, Sforza, Pachacuti, Prithviraj, Historical Campaigns
Kcam1-3: Tamerlane, Ivaylo, Kotyan
Rcam1-4: GajahMada, Suryavarman, Bayinnaung, LeLoi
Xcam1-3: Attila, ElCid, Montezuma

**Special note: If you use the historical battle background then the path is textures/campaign/fcam7/forgotten_background.dds

I-04 SlideImageSequence

I-04 SlideImageSequence

Relative position in json:

General format is:
"SlideImageSequence": "textures/campaign/campaign name/(write number for multiple scenarios, not for single scenario)/intro/%d.png",(in)
"SlideImageSequence": "textures/campaign/campaign name/(write number for multiple scenarios, not for single scenario)/outro/%d.png",(out)

* The path where the general slide images are placed inside the mod: widgetui\textures\campaign\campign name\(scenario name)\intro or outro
**The number of slides must be equal to the text, otherwise the black and white frame appears.
***The official resolution of the slideshow is 2000x1048, so it is recommended to set your slideshow to this resolution.
****If there is a need to add or change slides, you must see the effect of the change by restarting the game. (Delete does not require restart)

I-05 Slide Narration Voice (Sound)

I-05 Slide Narration Voice (Sound)

Relative position in json:

General format is:
"Sound": "Audio filename",

*All audio (including those in scenes) is placed in the path of the mod: resources\_common\drs\sounds
**Audio format as .wem(see Appendix 4-6 for the specific conversion audio portal)

I-06 Slide Duration and Text Fade Out Time (Duration; TextFadeDuration)

I-06 Slide Duration and Text Fade Out Time (Duration; TextFadeDuration)

Relative position in json:

General format is:
"Duration": 15.23,
"TextFadeDuration": 13.81,


*Digital units are seconds, only the former has been tested to control the playback time of the slideshow, the latter can be set at will, the role is unknown.
**It is recommended that you control the projection time when producing, and the voice of the narrator should be synchronized with the voice of the narrator, so the campaign with the voice of the narrator should not be played faster.

I-07 Image Controls (ImageRect)

I-07 Image Controls (ImageRect)

Relative position in json:

General format is【Official transparent slide standard configuration】
"ImageRect": {
"x": 910,
"y": 550,
"width": 2000,
"height": 1048
},

Example image:


*x, y refers to the x, y coordinates of the top left corner of the image
width, weight refers to the width and height of the image (control scaling)
**Each slide can have a separately defined image control, which allows each picture to have its own resolution scaling. If the next slide is not defined separately, the image controls of the previous slide are used.

***Special form 【standard for background non-transparent images】【best displayed when the resolution of non-transparent images is 2000x1048】
"ImageRect": {
"x": 860,
"y": 435,
"width": 2092,
"height": 1328
},

Example image:

I-08 Text Contents (String)

I-08 Text Contents (String)

Relative position in json:

General format is:
"String": "Text contents",

* Where "text content" can be a string of numbers predefined in the string table, or it can be ready-made text enclosed in double quotes.

EXP：
"String" : 65335,
"String" : "One paragraph of text contents",

**The "\" escape character is needed if you want to use both single and double quotes in the text.
*** If you want to achieve a line break or a blank line, add "\n" in front of the blank line or line break. Add a "\n" for a line break, and add n+1 "\n" to blank n lines.


Realization renderings: (blank lines and line break) 【Above and Below】

I-09 TextRect Controls (TextRect)

I-09 TextRect Controls (TextRect)

Relative position in json:

General format is:

"TextRect": {
"x": 1250,
"y": 660,
"width": 1410,
"height": 324
}

*x, y refers to the x, y coordinates of the top left corner of the text box
**X range [0:3840] Y range [0:2160]
***width is the length of a line, generally speaking, a English letter or punctuation is about 20, the full screen range of 3840, height even if limited height, the text will still exceed the lower border.
**** Try to control the length of the line width to avoid awkward breaks that affect the aesthetics and understanding.

II Layout json Great Exploration

II-01 Overview of layout.json

II-01 Overview of layout.json

Layout json, formatted as "campaign_layout.json"
It mainly controls the scenarios selection of the background map, chapter icons and various text boxes.

Layout json is divided into the following main modules.
○1 Custom Materials & Scenarios Selection Backgrounds (UserMaterials)
○2 Main Title Label (TitleLabel)
○3 Subtitle Box (LobbyBox)


Widget：
○4 Chapter Icon Button under the Main Component (Button, Image)
○5 Questions about ZPlane Disabling
○6 Chapter Icon Button Four States (Disabled, Normal, Hover, Pressed)

ChildWidgets：
○7 Sub-part 1: Scenarios Title Position & Black Translucent (CampaignTitle)
○8 Sub-part 2: White Curve Border (ClippingOverride)
○9 Sub-part 3: Difficulty Sword Setting (Level)
○10 Sub-part 4: Scenarios Text Box Color & Font Size & Text Content Setting
○11 Additional Part 1: Hover Text Box Battle Category Label (DataValue)
○12 Additional Part 2: Hover Text Box (Help)
○13 Additional part 3: Button Pressed Sound (ClickSound)

II-02 Custom Materials (UserMaterials)

II-02 Custom Materials (UserMaterials)

Relative position in json:

General format is：

{
"UserMaterials":[
{
"Material": "CampaignBackgroundXX",
"FileName": "Scenarios Selection Background Name.dds",
"Blend": "None"
},
{
"Material": "CampaignIconNumberXXNormal",
"FileName": "IconName_normal.png",
"Blend": "InverseAlpha"
},
{
"Material": "CampaignIconNumberXXHover",
"FileName": " IconName_hover.png",
"Blend": "InverseAlpha"
},
{
"Material": "CampaignIconNumberXXPressed",
"FileName": " IconName_pressed.png",
"Blend": "InverseAlpha"
},
{
"Material": "ButtonRedLuxury",
"FileName": "red_button.png",
"Blend": "None"
}
],
"BackgroundMaterial": "CampaignBackgroundXX",

*The path of the custom materials placed inside the mod: resources\_common\campaign
(The path cannot be wrong)
**General scenarios selection of the background image resolution should be 5684x2160 or 5120x2160, the specific conversion method portal sees Appendix 4-7
***The names of the chapter icons and the names of the backgrounds of the scenario's selection is given here as examples only for the sake of standardization and unity, and it is recommended to name them in this way.
**** Blend column can be written as None, the way it is written here is just strictly in accordance with the official material.json writing method.
*****Here the square brackets must be followed by a comma! The way BackgroundMaterial and Material are written is just a matter of convention and specification.
******You must define UserMaterials before you can use custom materials! The Material defined above must correspond to the Material used below, and must be checked for spelling.

Custom materials storage schematic image: (Has been explored: chapter icons, scenarios selection maps, sub-text boxes and the call of help images)

Regarding the writing of the official materials scenarios' selection maps and chapter icons, it is recommended to consult material.json for more comprehensive data information.

Significance: Now you don't need to modify materials.json to use custom backgrounds,so you don't need to consider the big trouble of updating materials.json by the officials, you can easily solve it through layout.json once and for all. This has epochal significance for the production of the campaign: there is no need for another player to manually install a custom map, the campaign author can handle it himself.

II-03 Main-title Label (TitleLabel)

II-03 Main-title Label (TitleLabel)

Relative position in json:

General format is

{
"Widget": {
"Type": "Label",
"Name": "TitleLabel",
"ViewPort": {
"xorigin": 1920,
"yorigin": 110,
"width": 1000,
"height": 100,
"alignment": "CentreCentre"
},
"StateMaterials": {
"StateNormal": {
"Font": {
"FontIndex": 0,
"PointSize": 70,
"Style": "Normal",
"TextColor": {
"r": 57,
"g": 28,
"b": 27,
"a": 255
}
}
}
},

"Text": "Main-title Text",
"TextAnchor": "CentreCentre",
"ChildWidgets": []
}
},


*Basically, it is ok to copy this paragraph by default here, just need to pay attention to the red bolded font and remember to change the text of the main title. If this module is missing, the default will be named according to the file name of the text centered on the top, plus this paragraph text will be centered overall.

II-04 Custom Styles for Main Header Box

II-04 Custom Styles for Main Header Box

Relative position in json:


General format is：

{
"Widget":{
"Type":"Base",
"Name":"BackgroundDecorationTitle",
"ViewPort":{
"xorigin":1920,
"yorigin":100,
"width":1500,
"height":200,
"alignment":"CentreCentre"
},
"ZPlane":3,
"StateMaterials":{
"StateNormal":{
"Material":"BackgroundDecorationTitle"
},
"StateDisabled":{
"Material":"BackgroundDecorationTitle"
}
},
"ChildWidgets":[
{
"Widget":{
"Type":"Label",
"Name":"TitleLabel",
"ViewPort":{
"xorigin":750,
"yorigin":110,
"width":550,
"height":100,
"alignment":"CentreCentre"
},
"ClippingOverride":"Background",
"StateMaterials":{
"StateNormal":{
"Font":{
"FontIndex":0,
"PointSize":70,
"Style":"Normal",
"TextColor":{
"r":57,
"g":28,
"b":27,
"a":255
}
}
}
},
"Text":"The replacement of the text of the Main Title",
"TextAnchor":"CentreCentre",
"ChildWidgets":[]
}
}
]
}
},

*If the main title is too long, you need to adjust the red bolded width value, otherwise the text will be scrolled horizontally. If you do not want to change the style of the main header box, then needn’t write.
**Just need to pay attention to the red bolded font and remember to change the text of the main title. Material materials can be selected in the following catalogs of appropriate materials: 1. widgetui\textures\menu\buttons 2. widgetui\textures\menu\decoration

***The problem about ZPlane writing: the value of ZPlane here must be >= 2 to achieve the replacement of the main header box custom style. Otherwise, the original title and the replacement title will be stacked up and cannot be read clearly.
****This feature has version restrictions, tested 37906+ version available, the previous version may not be available, please note the version information.

The following is the schematic images of the two cases:

The Correct Case "ZPlane":3,

The Error Case "ZPlane":1,

II-05 Sub-title Box (LobbyBox)

II-05 Sub-title Box (LobbyBox)

Relative position in json:


General format is：

{
"Widget": {
"Type": "Base",
"Name": "LobbyBox",
"ViewPort": {
"xorigin": 1920,
"yorigin": 200,
"width": 1000,
"height": 100,
"alignment": "CentreCentre"
},
"Image": {
"xorigin": 0,
"yorigin": 0,
"width": 1000,
"height": 100,
"alignment": "TopLeft"
},
"StateMaterials": {
"StateNormal": {
"Material": "ButtonExitNormal"
}
},
"ChildWidgets": [
{
"Widget": {
"Type": "Label",
"Name": "AuthorLabel",
"ViewPort": {
"xorigin": 204,
"yorigin": 28,
"width": 1000,
"height": 100,
"alignment": "TopLeft"
},

"StateMaterials": {
"StateNormal": {
"Font": {
"FontIndex": 0,
"PointSize": 45,
"Style": "Normal",
"TextColor": {
"r": 255,
"g": 255,
"b": 255,
"a": 255
}
}
}
},
"Text": "Author Infomation",
"TextAnchor": "TopLeft",
"ChildWidgets": []
}
}
]
}
},

*The xorigin and yorigin under the first Viewpoint refer to the x, y coordinates of the overall viewpoint origin of the signature bar, in the range of 3840 x 2160.
The width and height refer to the overall width and height of the byline window, the contents of the window can only be displayed, the part outside the range will be blocked and hidden, the sub-text box is generally filled with author information, you can adjust these two parameters as needed.
**The xorigin and yorigin under Image refer to the x, y coordinates of the origin of the background plate of the signature bar, which is generally set to 0,0 by default. width and height refer to the width and height scaling of the background plate of the signature bar, which can adjust the size of the image scale.
(It is recommended that all these two parameters in this module should be consistent to show the best results, to avoid unnecessary trouble)
***The Name inside the layout.json can be modified at will, but the type of Type must be accurate, so this paragraph just pay attention to the red bolded part and modify the corresponding text and several location parameters, the color of rgba can be adjusted by yourself, and the other can be copied as the example. (This module can be deleted if not necessary)
****The xorigin and yorigin under Childwidgets refer to the x, y coordinates of the top left vertex of the text box in the text box. The width and height refer to the width and height limits of the text in the textbox. If the text is too long and the width of the text box is not long enough will be the case of horizontal scrolling text. Text can use "\n" to achieve line breaks but all parts of the height should be doubled accordingly, but the performance effect is not good, so you should try to avoid line breaks in the sub-title box.
*****The StateMaterials segment in Image and Widget can be deleted to achieve a text-only effect without images (You are welcome to try it).

Schematic image of the effect:


*****You can add more than one sub-text box and also implement vertical text boxes.
json code:



Schematic image of the effect:

Base's alternative play
The layout.json can add more than one multiple Base segments, Base segment material can use any image (including chapter icons, text boxes, background images, etc.). It is almost universal that this can make a lot of new patterns.

Examples are as follows:

II-06 Chapter Icon Button under the Main Component (Button, Image)

II-06 Chapter Icon Button under the Main Component (Button, Image)

Relative position in json:

General format is：

"Widget": {
"Type": "Button",
"Name": "ScenarioButton1",
"ViewPort": {
"xorigin": 1570,
"yorigin": 590,
"width": 256,
"height": 320,
"alignment": "TopLeft"
},
"Image": {
"xorigin": 0,
"yorigin": 0,
"width": 256,
"height": 320,
"alignment": "TopLeft"
},

*The xorigin and yorigin in Viewpoint refer to the x and y coordinates of the top left vertex of the chapter icon button on the screen, while the two parameters under Image refer to the top left corner of the chapter icon, which is the starting point of the chapter icon image (0,0)

*The width and height refer to the width and height of the chapter icon button, which can be scaled. If the original resolution of the image is to be displayed, twice as large as the original pixels of the image should be used. (In addition, there is a limit to the maximum visible window of the image, when the image > window, the image will be displayed incomplete. So, if you want to scale the image, it is best to modify the image width and height in sync with the Image below)
**The width and height in the Image refer to the image size of the chapter icon button on the map, (actually twice as large as the actual image size of the StateMaterials behind) and it is best that the image size be equal to the width and height of the button.
***The general parts to be modified in this paragraph are the four parameters of Viewpoint and the two parameters of width and height of Image.

【Tips for quickly modifying the xy coordinates of the multi-scenarios campaign chapter icon button】
Here is a quick way to modify it.

• 1. Change the "Name": "ScenarioButton2", line of the second scenario to "Name": "CampaignButton2", it's OK. This will show all the scenarios.
  
• 2. Adjust all chapter icon button x, y coordinates.
  
• 3. Change the "Name": "CampaignButton2", line of the second scenario back to "Name": "ScenarioButton2", (The reason is unknown, if you do not change it back, you cannot enter the scenario after clicking the chapter icon)

Display principle and law:


The effect before modification:


The effect after modification:

II-07 Questions about ZPlane Disabling

II-07 Questions about ZPlane Disabling

Regarding the location of ZPlane, the official documentation appears three times, after the main textbox module Viewpoint, after the button module Image and after the sub-part 1: scenarios title module Viewpoint.
After experimental tests are listed as follows: (defined as Z1, Z2, Z3) 0 is no and 1 is yes

*Comprehensive conclusion: in the presence of Z1, the text of the main text box disappears, in the presence of Z2, both the image of the chapter icon and the text disappear, and the presence or absence of Z3 has no effect on the text of the main text box and the image of the chapter icon.
**In short, delete all the ZPlane lines when making layout.json in custom campaigns. (Except for special cases such as changing the style of the main title box) 【See II-04 Custom Styles for Main Header Box】

II-08 Chapter icon button four states (Disabled, Normal, Hover, Pressed)

II-08 Chapter icon button four states (Disabled, Normal, Hover, Pressed)

Relative position in json:

General format is：

"StateMaterials": {
"StateDisabled": {
"Font": {
"FontIndex": 0,
"PointSize": 34,
"Style": "Normal",
"TextColor": {
"r": 42,
"g": 10,
"b": 82,
"a": 128
}
}
},
"StateNormal": {
"Material": "CampaignIconXXNormal",
"Font": {
"FontIndex": 0,
"PointSize": 34,
"Style": "Normal",
"TextColor": {
"r": 42,
"g": 10,
"b": 82,
"a": 255
}
}
},
"StateHover": {
"Material": "CampaignIconXXHover",
"Font": {
"FontIndex": 0,
"PointSize": 34,
"Style": "Normal",
"TextColor": {
"r": 42,
"g": 10,
"b": 82,
"a": 255
}
}
},
"StatePressed": {
"Material": "CampaignIconXXPressed",
"Font": {
"FontIndex": 0,
"PointSize": 34,
"Style": "Normal",
"TextColor": {
"r": 42,
"g": 10,
"b": 82,
"a": 255
}
}
}
},

*Chapter icon has 4 states: disabled, normal, hover, pressed. This code only needs to modify the red bolded part can be, the rest can be copied as the example.
**If you use the official material, you will have to find it in the path of the game itself: widgetui\textures\campaign\campaign_selection\campaign_icons, and uniformly named as CampaignIcon+number+campaign name+status.


If you are using historical battles material, you should look for it in the following path: widgetui\textures\campaign\campaign_selection\campaign_icons\historical_battles, and uniformly named as ScenarioIcon+number+campaign name+status.
All the campaign names are in English with the first letter of the word capitalized.

***If using custom chapter icons, it must be a Png image with a transparent background.
It is suggested to unify the name as CampaignIcon+number+campaign name+status.
****Special Note: The following icons appear in the historical battles' material path, but because they are not written in material.json, they can only be called in a custom way. (Hover is brighter and pressed is darker in the chapter icon production)

*****If you use the background of the scenarios' selection background used in front of you for the Art of War "BackgroundMaterial": "CampaignBackgroundChallenges", the icon line of the chapter icon button is recommended to be empty, and should be written as "Material": "",


*******Catalog Master List of Chapter Icons:

II-09 Sub-part 1: Scenarios Title Position & Black Translucent (CampaignTitle)

II-09 Sub-part 1: Scenarios Title Position & Black Translucent (CampaignTitle)

Relative position in json:

General format is：
"ChildWidgets": [
{
"Widget": {
"Type": "CampaignTitle",
"Name": "CampaignButton1Label",
"ViewPort": {
"xorigin": -80,
"yorigin": 315,
"width": 700,
"height": 100,
"alignment": "TopLeft"
},


* Here we need to pay attention to the Type must be CampaignTitle, otherwise it cannot appear black translucent, not to mention the official curve border and the gold, silver and bronze medal settings like the officials. The official authors only write here as ScenarioButtonLabel, this is a big wrong and it is impossible to come out of any curve border, so we must avoid it.

** Here you need to adjust the parameters xorigin and yorigin, adjust the position of the text box under the chapter icon button, try to consider the aesthetics. (The starting point of the child part is the top left corner of the parent part window. Here fill in 0 that means x coordinate = x coordinate of the parent part. x can be filled with a negative number, which means offset to the left, y is generally a positive number)

***height parameter setting rules: when using the Art of War background map is recommended to be set to 900, the rest of the case is recommended to be set to 700.

Aesthetic renderings: (general x range -200~80, y range 220~280)

II-10 Sub-part 2: White Curve Border (ClippingOverride)

II-10 Sub-part 2: White Curve Border (ClippingOverride)

Relative position in json:

General format is：
"ClippingOverride": "Background",



*Without this line the text will be obscured (so that the text box can be displayed beyond the parent widget window ViewPort. If this line is removed, the text box will only fit inside the parent widget viewport and thus may not be displayed completely. Removing this line from the battle will also result in the loss of the text box border decoration)
**As mentioned above, the front Type must be CampaignTitle, and the back must be written this way in order for the official curve border to appear, otherwise even if the back is correct but the front is not, the white curve border will still not appear. The appearance of the white curved decorative frame can only appear the effect of gold, silver and bronze medals in the situation of passing the scenarios.
***Basic logic: black translucent -> white curve border -> gold, silver and bronze medals


Schematic diagram of the principle:

II-11 Sub-part 3: Difficulty Sword Setting (Level)

II-11 Sub-part 3: Difficulty Sword Setting (Level)

Relative position in json:

General format is：
"Level": 0,

* Role of Level: (No level defaults to 0)
【All of the above include the right endpoint and do not include the left endpoint】

<0 Prefixed spaces
=0 Normal display without spaces
0~2.5 Difficulty one sword
2.5~3 Difficulty two swords
3+ Difficulty three swords

Schematic diagram of the principle:

** The difficulty sword setting can tell the player the scenarios of difficulty from the designer's/ translator's point of view, which can play a good role in guiding the player in advance to psychological compiling. (Of course, except for the player head iron haha)

II-12 Sub-part 4: Scenarios Text Box Color & Font Size & Text Content Setting

II-12 Sub-part 4: Scenarios Text Box Color & Font Size & Text Content Setting

Relative position in json:

General format is：

"StateMaterials": {
"StateNormal": {
Font": {
FontIndex": 0,
"PointSize": 45,
"Style": "Normal",
"TextColor": {
"r": 255,
"g": 255,
"b": 255,
"a": 255
}
}
}
},
"Text": "Scenario Name",
"TextAnchor": "TopLeft",
"ChildWidgets": []
}
}
],


*This paragraph needs to modify the parameters for the red bolded part and rgba, where the four parameter numbers are all set to 255(white color) . The rest can be copied as the example.

** a(alpha) range 0~255(128 for translucent, 255 for opaque)

*** PointSize parameter setting: In addition to the Art of War selection background is recommended to be set to 135(large enough to be clear), the rest of the scenario's selection background is recommended to be set to 45.

****The Art of War selection background for CampaignBackgroundChallenges, rgba's four parameter numbers are set to 10,40,10,255.

***** If there are no additional parts to follow, no comma can be added after the brackets here, but a comma must be added if there are additional parts to follow.

II-13 Additional Part 1: Hover Text Box Battle Category Label (DataValue)

Additional Part 1: Hover Text Box Battle Category Label (DataValue)

Relative position in json:

General format is:
"DataValue": [],
The role of DataValue[x,y]: (x,y must be integers)

• x=1 Conqueror Campaign
  
• x=2 Forgotten Empires Campaign
  
• x=3 African Kingdoms Campaign
  
• x=4 Rise of the Raja Campaign
  
• x=5 The Last Khan Campaign
  
• x=6 Definitive Edition Campaign (specifically The Art of War)
  
• x=7 Conqueror and Forgotten Empires Campaign (Historical Battles)
  
• x=other integers (<=0 or >=8) Age of Kings Campaign

The value of y for custom campaign can be any integer. (Role: Official Index)

**Prerequisite for using DateValue: The "Type" line in Section II-06 should be rewritten as "Type": "CampaignButton", If you do not want the DateValue effect, write "Type": "Button" as described in section II-06. If you don't change the "Type" line in front of it, the DateValue effect will not be displayed.

***If you write "Type": "CampaignButton" in front of it, it will show the effect of Age of Kings Campaign by default even if the DataValue line is missing.

Modify the code in Section II-06 as follows:



The display renderings are as follows:
X=1


X=2


X=3


X=4


X=5


X=6


X=7


X=Other/No such line

II-14 Additional Part 2: Hover Text Box (Help)

II-14 Additional Part 2: Hover Text Box (Help)

Relative position in json:

General format is：
"Help":"<color/italic code> Hover Hint Content",

*Help controls the white font hints displayed in the lower right corner when the cursor hovers over the chapter icon, and each scenario can have a paragraph of hints.
**If you want to use single and double quotes in the text, you need to add the "\" escape character.
*** If you want to achieve a line break or a blank line, add "\n" in front of the blank line or line break. Add a "\n" for a line break, and add n+1 "\n" to blank n lines.
**** Text mod string ID, string quote code, and double-quoted text are both available.
Exp：
"String" : 65335
"String" : "Text contents"
"String" : "IDS_RESTORE_SCREEN_LISTBOX_HELP"

***** Supplement: About <color/italic code>
Now the help text can be used to change the color and use italics, the code is as follows:

<blue>


<red>


<orange>


<yellow>


<cyan>


<grey>


<purple>


<i>


You can use a variety of colors/italics in the same help text, and if a paragraph is too long, switching effects may force a line break.
Format: <xx>Text<xx>Text


You can use the image call (official material.json or custom materials) to define the image material format 【See section II-02 for details of the custom material method】 to define the code <material=xx,1>

○1. xx is the custom material Material or official call name.
○2. For the caling multiplier, the default is 1, >1 zoom, <1 shrink, can be a decimal (Figure 1) to take 0 or <0 is no image display, to take a negative number will lead to the picture call behind the font left to produce a mixed effect, very bad effect. (Figure 2)
○3. If you call the official random map overview/official icon as help decorations, the recommended scaling multiplier is 0.7/0.9 for best results (Figure 3). Of course, you can also call two official random maps as decorations (scaling multiplier 1) (Figure 4)

Figure 1


Figure 2


Figure 3


Figure 4


Cautions:
1.You cannot use <green>, otherwise it will flash back, the above code can be case sensitive.
2.You can use Color + Italics, but it must be <color> <i> order to correctly display the colorful italic words, because the default is to read the color first.
3. Personally, I recommend using light-colored fonts (red, orange, yellow, and cyan), so that the display can be clearer.
4. If you don't write <color> code, it will default to white color, if you want to revert to white from other colors, then use <default>.
5. The italic will affect the DLC hat font orthographic italic but the color will not affect this.
6. Official random map overview call path is textures/menu/mapicons/xx.dds and call name is IconXx (Example: IconArena first letter capitalized)

Effect display：
<i><red>


<red> <i>



Schematic image of the effect:


Significance: About the use of the help can give the author the opportunity to make a brief introduction to the campaign, enriching the style of the campaign production, where the relevant historical background can be introduced to give the player a preliminary understanding of the campaign.

II-15 Additional part 3: Button Pressed Sound (ClickSound)

II-15 Additional part 3: Button Pressed Sound (ClickSound)

Relative position in json:

General format is:
"ClickSound": "Play_Button_GFX"
*Remember never to add a comma at the end of this line.
**The sound effects when the button is pressed (we can replace the sound effects for the clicked button with new ones, or call the sound effects that come with the Age of Empires II Definition Edition (check the audio source table in the tutorial))
***The newly added audios storage path is resources\_common\drs\sounds, see Appendix 4-5 for the audio source table in the tutorial.

II-16 Text Arrow Widget (Next Indicator)

II-16 Text Arrow Widget (Next Indicator)

Relative position in json:


General format is:

{
"Widget": {
"Type": "Base",
"Name": "NextIndicator1",
"ViewPort": {
"xorigin": 1869,
"yorigin": 637,
"width": 277,
"height": 182,
"alignment": "TopLeft"
},
"Wrap": {
"width": 0,
"height": 0
},
"StateMaterials": {
"StateNormal": {
"Material": "ArrowLianYouGuo1"
}
},
"ChildWidgets": [
{
"Widget": {
"Type": "Label",
"Name": "NextIndicator1Label",
"ViewPort": {
"xorigin": 0,
"yorigin": -50,
"width": 700,
"height": 100,
"alignment": "TopLeft"
},
"ClippingOverride": "Background",
"StateMaterials": {
"StateNormal": {
"Font": {
"FontIndex": 0,
"PointSize": 60,
"Style": "Normal",
"TextColor": {
"r": 114,
"g": 0,
"b": 0,
"a": 230
}
}
}
},
"Text": "Text arrow text",
"TextAnchor": "TopLeft",
"ChildWidgets": []
}
}
]
}
},

** Here you only need to pay attention to the red bolded font and remember to change the text and arrow material settings. The parameters that need to be modified in this section are the upper and lower pairs of xorigin, yorigin and rgba, and the rest can be copied as the example.
**Arrow material (a total of 8) in the forum there are resources to download, you must use the custom material call method, see section II-02 for details, here will not repeat.
*** This part is the arrow between the nth scenario and the n+1st scenario, which appears after the nth scenario is passed. In order of parts, 1 part appears for each scenario passed.
**** ChildWidgets are text boxes that appear in sync with the arrows.

The description of Wrap is to be updated later.

Renderings:


Significance: The use of arrows broadens the new way of layout use.

III Appendix

III-1 Appendix 1: Compiling of info.json

III-1 Appendix 1: Compiling of info.json

Info.json is used to read the mod background image, mod title, mod description and mod author. It is placed on the same layer as thumbnail.png.

General format is：
{"Author":"XX","Description":"Description text","Title":" XX "}

*Description can be empty, write as "Description": "No Description",
**This json must exist, otherwise the mod information cannot be read.
*** If you want to use single and double quotes in the text in Description, you need to add "\" escape character; if you want to achieve a line break or blank line, add "\n" in front of the blank lines or line break.
**** If you want to achieve a line break or a blank line, add "\n" in front of the blank line or line break. Add a "\n" for a line break, and add n+1 "\n" to blank n lines. Use English double quotes for the text of custom campaigns.
***** Of course, you can also add self-explanatory documents like readme.txt.

III-2 Appendix 2: Standard Process of HD Scenarios to DE

III-2 Appendix 2: Standard Process of HD Scenarios to DE

The standard process for HD to DE remaking is as follows.
1. in the scx2/aoescenario message section:
History -> the intro slideshow
Victory -> the outro slideshow
If HD originally has json, then json content -> Help
The script guidelines will be determined on a case-by-case basis.

2.Each remaking HD campaign must include slide json, layout.json, info.json, and need to make slides and thumbnail.png according to the content of your choice.
3.About HD original sound for mp3 format, DE for wem format, so the need for audio format conversion, see Appendix 4-6 for details.

III-3 Appendix 3: Suggestions for Making Mod Covers Images

III-3 Appendix 3: Suggestions for Making Mod Covers Images

1.About Mod cover image format thumbnail.png or _preview-icon.jpg, must be named like this, otherwise the mod cannot be read. Mod manager cover image frame is 282x158, aspect ratio 1.785.
2.The best format is png, common resolution 1024x512 or 800x600, but the best resolution to display is 1024x574 or 800x448. pictures will be automatically stretched according to the MOD manager, see Appendix 4-7 for details.
3. It is recommended to identify the English MOD name on the image, the specific method is to use the Photoshop.

III-4 Appendix 4: Various portals and reference documents

III-4 Appendix 4: Various portals and reference documents

1. Newtonerdai's slide json: https://www.hawkaoe.net/bbs/thread-145682-1-1.html
2. Newtonerdai's layout.json: https://www.hawkaoe.net/bbs/thread-145947-1-1.html
3. A few additional points about layout https://www.hawkaoe.net/bbs/thread-146187-1-1.html
4. Layout new era https://www.hawkaoe.net/bbs/thread-146275-1-1.html
5. DE audio call/modify/add guide https://www.hawkaoe.net/bbs/thread-145543-1-1.html
6. OPUS encoding of wav->wem transcoding https://www.hawkaoe.net/bbs/thread-146166-1-1.html
7. Background image processing https://www.hawkaoe.net/bbs/thread-146250-1-1.html
8. Create a string mod method https://www.hawkaoe.net/bbs/thread-145598-1-1.html
9. Layout signature bar effect implementation and details https://www.hawkaoe.net/bbs/thread-146345-1-1.html
10. String table mod/text mod: a powerful tool for multilingual support https://www.hawkaoe.net/bbs/thread-146496-1-1.html
11. Summary of the conclusions about playing wem sound effects https://www.hawkaoe.net/bbs/thread-146546-1-1.html

III-5 Appendix 5: Postscript & Acknowledgements

III-5 Appendix 5: Postscript & Acknowledgements

Postscript:
The compilation of DE's JSON Kungfu Made in CHINA comes from Nguyen Duy Hung (Game name: Duyhung2h), the Master (The campaign author of Gensokyo - Season of Calamity) in an email back to me pointed out that the DE players for JSON research is still in its infancy, the urgent need for a guide to the campaign maker's treasure trove. In view of the Hawkaoe Forum inside the author and Newtonerdai on JSON has a certain degree of research, so the author will be the integration of the past several research posts so there is this article, hoping to be helpful to the campaign makers.
The author of the text is too shallow, if there are mistakes or new findings, welcome to inform the author, thank you to all readers who have made suggestions. This is a long time to update the JSON Kungfu Made in CHINA, I hope you can gain from it and learn what you want, thank you.

Special thanks to New-Barbarossa-Tone for his hard work in reviewing and correcting this article.


Cly806
2020.05.28 First Draft
2021.05.28 English Version Translation

Contact the Author: [e-mail]
Acknowledgements: Newtonerdai, Hudson, Kuro, Duyhung2h

[LinhIsHereeee]

Thanks for the comprehensive documentation, I have to admit I didn't have the patience to write a guide on my own but I've shared my viewpoints. It's easy enough to handle .json files without any prior programming knowledge, so I recommend everyone give this guide a read.

[lsy371482850]

可以可以~~~

[Minglan_Sheng1016]

Hi igrohp,you can translate it into spainish,then other person will do it spainish->english,because spainish is similar to english,I believe you can finish it well.

[igorhp]

It seems a very complete and exhaustive guide... translate it to another language must be very hard, at least, it would be good a english translation. Sorry for my english

[Wolotine]

支持一波