0 A.D's Built-in Encyclopedia

[ShadowOfHassen]

1 hour ago, Vantha said:

Thanks.

Well, the log files didn't contain any error messages last time... Is the crash message the same as before?

Pretty much, after I dismiss the error the entire game window gets wonkey.

[Vantha]

52 minutes ago, ShadowOfHassen said:

Pretty much, after I dismiss the error the entire game window gets wonkey.

Does deleting the 'simulation' folder help?

It only contains (currently unused) links to some articles inside the XML templates.

Edited June 11 by Vantha

[ShadowOfHassen]

https://github.com/TheShadowOfHassen/0-ad-history-encyclopedia-mod/pull/149

 

I decided we've had to much exciting encyclopedia news so here's another PR of boring edits, this time for the mixins we made for articles.

[ShadowOfHassen]

Pr for Atenian structures

 

https://github.com/TheShadowOfHassen/0-ad-history-encyclopedia-mod/pull/150

[ShadowOfHassen]

PR for Athenian Units

 

https://github.com/TheShadowOfHassen/0-ad-history-encyclopedia-mod/pull/151

[Vantha]

I opened a second editing pr for some Athenian units that were left untouched in the first one

https://github.com/TheShadowOfHassen/0-ad-history-encyclopedia-mod/pull/152

[Vantha]

.

Edited July 2 by Vantha
posted by accident

[Vantha]

Big news regarding the encyclopedia page!

New features:
- the ability to put images in the article header. I decided to place the images to the top right and the title to the top left. This saves a lot of space compared to other possibilities and it looks good with images of most aspect ratios. But I will talk more in depth about the implementation in a future post.
- the ability to add subtitles. They are fully optional, but really enhance the header's visual appeal (in my opinion).
- a button below the title that opens up the the template viewer showing the unit's in-game stats. Its portrait is embedded into the button, so players can visually recognise the unit from in-game as well.
- buttons to directly switch to the next or previous article in the same subcategory (to the suggestion of @nifa)
They currently do not include any text as I think the arrow sprites are enough of a hint as to what the buttons do.

Here is a quick showcase:

 

Other improvements:
- fixed GUI scaling on lower screen resolutions (down to 1024x768). This turned out as quite a hassle, but it had to be done eventually. I haven't tested it on large screens (yet), mainly because they usually don't cause problems. If you notice any problem with the GUI scaling, let me know.

 

As always I packed it into a mod, please try it out, any feedback is welcome!

encyclopedia.zip

 

(unfortunately I have not yet managed to resolve the issue with the crashes, I recommend trying to open it multiple times and supressing the error, if you notice any patterns or have any idea on how to resolve it, please let me know)

[ShadowOfHassen]

53 minutes ago, Vantha said:

Big news regarding the encyclopedia page!

New features:
- the ability to put images in the article header. I decided to place the images to the top right and the title to the top left. This saves a lot of space compared to other possibilities and it looks good with images of most aspect ratios. But I will talk more in depth about the implementation in a future post.
- the ability to add subtitles. They are fully optional, but really enhance the header's visual appeal (in my opinion).
- a button below the title that opens up the the template viewer showing the unit's in-game stats. Its portrait is embedded into the button, so players can visually recognise the unit from in-game as well.
- buttons to directly switch to the next or previous article in the same subcategory (to the suggestion of @nifa)
They currently do not include any text as I think the arrow sprites are enough of a hint as to what the buttons do.

Here is a quick showcase:

 

Other improvements:
- fixed GUI scaling on lower screen resolutions (down to 1024x768). This turned out as quite a hassle, but it had to be done eventually. I haven't tested it on large screens (yet), mainly because they usually don't cause problems. If you notice any problem with the GUI scaling, let me know.

 

As always I packed it into a mod, please try it out, any feedback is welcome!

encyclopedia.zip 14.5 MB · 1 download

 

(unfortunately I have not yet managed to resolve the issue with the crashes, I recommend trying to open it multiple times and supressing the error, if you notice any patterns or have any idea on how to resolve it, please let me know)

It. Looks. AMAZING!!!

So what are the next steps? Fix the bug then convert previous articles, then merge? Or should we do a hybrid. Fix bug, merge, work converting articles and add them directly to game?

On one hand, we might not want to ship something uncompleted.

 

On the other hand, this is an open source project. (Joke, don't hit me!)

Also, it might be easier to figure out where all the files go in the main game with only a few articles than a billion.

[guerringuerrin]

This is awesome! Is this actually working? I tried installing it on my a26 version but the button didnt appear at the main menu

[Grautvornix]

8 hours ago, ShadowOfHassen said:

It. Looks. AMAZING!!!

So what are the next steps? Fix the bug then convert previous articles, then merge? Or should we do a hybrid. Fix bug, merge, work converting articles and add them directly to game?

On one hand, we might not want to ship something uncompleted.

 

On the other hand, this is an open source project. (Joke, don't hit me!)

Also, it might be easier to figure out where all the files go in the main game with only a few articles than a billion.

That's phantastic! Although yet no fully completed,  I'd vote for including it into the mod.io or even SVN as part of vanilla version so everyone can get inspired.. Excellent job! Well done!

[Vantha]

12 hours ago, ShadowOfHassen said:

It. Looks. AMAZING!!!

So what are the next steps? Fix the bug then convert previous articles, then merge? Or should we do a hybrid. Fix bug, merge, work converting articles and add them directly to game?

On one hand, we might not want to ship something uncompleted.

 

On the other hand, this is an open source project. (Joke, don't hit me!)

Also, it might be easier to figure out where all the files go in the main game with only a few articles than a billion.

3 hours ago, Grautvornix said:

That's phantastic! Although yet no fully completed,  I'd vote for including it into the mod.io or even SVN as part of vanilla version so everyone can get inspired.. Excellent job! Well done!

I suggest we add the page to the game now (after fixing the bug), but only with selected articles for testing. The review process will take a lot of time anyway and in parallel we can already "customize" the rest of the articles (adding images, subtitles, links to other articles, etc.). And as soon as the page framework is merged we can add the bulk of articles to the game too. I don't think incompletion is be something to worry about in this case, since the page framework is indeed complete and we can simply remove the button from the main menu as long as it doesn't contain all the articles to prevent players from finding a (seemingly) incomplete and empty page in a full release. And the existence of temporarily unused files in 0ad's code wouldn't be anything new either. Howevere, I will talk to some developers and adapt to what they deem best.

 

10 hours ago, guerringuerrin said:

This is awesome! Is this actually working? I tried installing it on my a26 version but the button didnt appear at the main menu

I made the mod for the latest version, but it should be working with A26 (except the unit portraits) as well. Have you verified the mod is installed properly? Does anyone else face the same issue?

You can try opening the javascript console with the assigned hotkey (per default '^' and F9) and entering the following command:

Engine.SwitchGuiPage("page_encyclopedia.xml");

[ShadowOfHassen]

1 hour ago, Vantha said:

I suggest we add the page to the game now (after fixing the bug), but only with selected articles for testing. The review process will take a lot of time anyway and in parallel we can already "customize" the rest of the articles (adding images, subtitles, links to other articles, etc.). And as soon as the page framework is merged we can add the bulk of articles to the game too. I don't think incompletion is be something to worry about in this case, since the page framework is indeed complete and we can simply remove the button from the main menu as long as it doesn't contain all the articles to prevent players from finding a (seemingly) incomplete and empty page in a full release. And the existence of temporarily unused files in 0ad's code wouldn't be anything new either. Howevere, I will talk to some developers and adapt to what they deem best.

 

I made the mod for the latest version, but it should be working with A26 (except the unit portraits) as well. Have you verified the mod is installed properly? Does anyone else face the same issue?

You can try opening the javascript console with the assigned hotkey (per default '^' and F9) and entering the following command:

Engine.SwitchGuiPage("page_encyclopedia.xml");

So the way I see it we should proceed like this 

 

1. Fix bug 

2. add engine code (with minimal articles to mainline 

3 add the rest of the articles  directly to svn

4 finish writing articles and adding them to svn (or git if it shows up first 

[wowgetoffyourcellphone]

Looks nice. Make sure that hoplite image is CC0 or CC-BY-SA or equivalent.

I would quibble with the organization of the articles, but I'm not going to criticize too hard given the good amount of progress shown here. Carry on my wayward sons!

[ShadowOfHassen]

5 minutes ago, wowgetoffyourcellphone said:

Looks nice. Make sure that hoplite image is CC0 or CC-BY-SA or equivalent.

I figured we could start with images from Wikipedia . I'm pretty sure their pictures are in CC in some way.

 

6 minutes ago, wowgetoffyourcellphone said:

I would quibble with the organization of the articles, but I'm not going to criticize too hard given the good amount of progress shown here. Carry on my wayward sons!

If you have a suggestion, tell us! The only way we can get better is if people tell us what we do wrong (or even what they disagree with)

[Vantha]

53 minutes ago, ShadowOfHassen said:

So the way I see it we should proceed like this 

 

1. Fix bug 

2. add engine code (with minimal articles to mainline 

3 add the rest of the articles  directly to svn

4 finish writing articles and adding them to svn (or git if it shows up first 

Yes, exactly.

 

34 minutes ago, wowgetoffyourcellphone said:

I would quibble with the organization of the articles, but I'm not going to criticize too hard given the good amount of progress shown here. Carry on my wayward sons!

The structure of the encyclopedia is not very hard change codewise. And as ShadowOfHassen said, we're more than open to suggestions!

Edited July 3 by Vantha

[wowgetoffyourcellphone]

1 hour ago, Vantha said:

The structure of the encyclopedia is not very hard change codewise. And as ShadowOfHassen said, we're more than open to suggestions!

Well, not to beat a dead horse, but my suggestions have already been made with crafted mockups. Whether you heed them or not is up to you.

 

I do like the unit stats popup instead of putting it all in the encyclopedia page as in my mockup. Nice. We'll just need to improve that popup sometime in the future too (and of course I have a mockup for that too).

[Vantha]

2 hours ago, wowgetoffyourcellphone said:

Well, not to beat a dead horse, but my suggestions have already been made with crafted mockups. Whether you heed them or not is up to you.

Well, it's not too different from the current system, is it? What is it in particular that's bothering you?

 

2 hours ago, wowgetoffyourcellphone said:

We'll just need to improve that popup sometime in the future too (and of course I have a mockup for that too).

Yes, I know! That has been on my radar for quite some time. It is way better structured and more visually appealing than what we currently have. And I plan to implement it sooner or later.

[Vantha]

I will submit a diff for the encyclopedia page soon. And while it's getting reviewed, we will start with the process of "customizing" the articles - adding titles, subtitles, images, related articles, references to xml templates, and some formatting to the text contents itself. There is a ton to say about the features' implementation and what to pay attention to. I tried my best to lay out the information as logically as possible and I'm open to explaining it further, if anything is unclear:

Spoiler

Customizing the articles:

The articles are stored in JSON files inside a directory structure (equal to the categorization structure on the GUI page). The categories' introductory overview texts are saved in the overview.json in the respective directory and are treated the same as all other articles.

Some notes ahead: Firstly, most of the following "modifications" already applied to the article "Athenian Hoplites" (0 A.D.'s civilizations/Athenians/Athenian military/Athenian Hoplites.json). It serves as a good reference on how things need to be done. Secondly, I highly recommend to actually open articles on the page after "customising" them to verify everything is displayed as intended. There are just so many different interconnected parameters, visualising it in the head can be hard. And double-checking has never hurt anyone.

Editing the JSON files

• the content property (obviously) contains the text contents
• the title property (obviously) contains the title shown above the text. (As a guide point for its length: Heading images with the widest possible aspect ratio (3:1) leave space for a title of about 22 characters in length on the smallest supported screens)
• the subtitle property can set a string of text that is displayed in a smaller font below the title. It can span over two lines which allows for relatively long subtitles (As a guide point for its length: Heading images with the widest possible aspect ratio (3:1) leave space for a subtitles of about 60 characters in length)
• the relatedArticles property specifies the articles linked to in the right page section. It has to be written as a list (enclosed in square brackets and seperated by commas) of strings storing the path to the target articles' json from the articles/ folder onwards. (meaning it has to start with "About/", "Nature and Environment/", "The Ancients World/", "0 A.D.'s civilizations/", or "Wars and Battles/")
• the parent property can specify a json file, from which all missing properties are inherited - essentially like template parents or mixins. The value has to be a string containing the target file's name (not the path to the file; only files inside gui/encyclopedia/articles/parents/ can be set as parents)
• the image property can store image data used to render an image to the right of the title. It has to be written as an object (in curved brackets) with two properties: the fileName property points to the image (png) file (inside art/textures/ui/encyclopedia/images). IMPORTANT: The engine can only read image files with width and height of powers of two, which drastically limits the number of aspect ratios. To circumvent this, images (of any aspect ratio) can be extended (by adding transparent pixels) outwards to achieve a width and height of the next larger power of two. The cropped property then stores the original image's resolution and the full property stores the final resolution after extending it. full is used to to calculate the actual size of the image object while cropped is used to align it (to the top right) and determine around what area (of opaque pixels) the border is placed and scaled to.
• the xmlTemplate property stores the data used for the template viewer button. It has to be defined as an object (in curved brackets) with two properties: icon determines which portrait icon to show on the button. data contains the data with which the template viewer is opened, it's comprised of:templateName containing the path to the XML file from the base folder simulation/templates (without the .xml file extension) and civ containing one of the civ codes (athen, brit, cart,...). The code for no civ is gaia. If no template is specified the button is simply disabled. One thing to note: The article setup script automatically assigned templates to the articles. If it didn't find an icon to use, it left it out. Articles without icon in their xmlTemplate will not (!) be rendered with a template viewer button.

Formatting
Tags can be added into the plain text to change how it is rendered like explained on the wiki here.
In the case of JSON files the quotation marks need to be escaped with a backslash.
Considering the default text size of articles is 18 pixels, a text passage can be set to bold with font=\"sans-bold-18\" and to italic with font=\"sans-italic-18\". Also, beware that the overview texts are of size 20 (not 18).
The best way to embed images into the text is by using the icon tag in between two line breaks: text above the image\n [icon=\"____\"]\ntext below the image (this places in between two lines of texts and works regardless of the image's size). Using 'displace' is a good way to move the image more towards the center. Beware that too high values can lead to the icon being cut off on smaller screen resolutions.
Also, the icon has to be defined in gui/encyclopedia/setup.js like shown here. The size of the icon should never be higher than the resolution of the image file. (By the way, the engine requires images to be PNGs and their height and width in pixels to be a power of two).

 

[nifa]

On 02/07/2024 at 11:51 PM, Vantha said:

- buttons to directly switch to the next or previous article in the same subcategory (to the suggestion of @nifa)
They currently do not include any text as I think the arrow sprites are enough of a hint as to what the buttons do.

Great work! That's exactly how I imagined it, thanks for your effort:) It looks really nice. cherry on top would be the possibility to use the keyboard for navigation:D

[Vantha]

3 hours ago, nifa said:

Great work! That's exactly how I imagined it, thanks for your effort:) It looks really nice. cherry on top would be the possibility to use the keyboard for navigation:D

Thanks.

Yeah, adding hotkeys for certain actions is definitely something I should (and will) be looking into in the future.

[Vantha]

Turns out, the crashes were caused by some corrupted png files. I'm neither sure what exactly damaged the file structure nor why it would sometimes work regardless, however, I was able to fix them. Here is an updated mod:

encyclopedia.zip

[guerringuerrin]

mod is working fine on my a27 compiled version!

[Vantha]

1 hour ago, guerringuerrin said:

mod is working fine on my a27 compiled version!

I'm glad to hear that!

[ShadowOfHassen]

So because we're going to start adding articles to mainline, (as soon as @Vantha gets the amazing new UI) there are a few things I'd like to discuss/ask.

First translating. I'm assuming it is just the community translates it? , will the new places we're putting the articles be able to be translated, and second how is translation done, and is there a set of guidelines because I think for anything not American English we can get rid of the US customary measurements, and I'd like the translators to know that.

Second. I know for a project like this, we have reviewers for code, art and even music, and I think we should have the same thing for large portions of text in game. Between @Vanthaand I we've put a lot of work into the encyclopedia so far, and I'd like to try and get the same quality of writing in the rest of the game. It would be great if whenever there's a patch with anything bigger than a tooltip, the devs could let me know, so I can give it a look and wait until we can get the text right before merging. Editing and in game text might not sound that important compared to art, code, or gameplay, but I'd still like to get it the best we can.

Besides, with rumblings of new tutorials, campaigns, and the like; someone to coordinate the narrative/writing side of things will help the devs time to be focused on things they are more interested in.

Edited July 8 by ShadowOfHassen