Factorio Forums

Posted: **Thu Apr 02, 2020 5:04 pm**

INTRODUCTION
Welcome to Booktorio!
This is a library mod designed to give a in game wiki to all mods that want one but don't want have to go crazy with the challenging Factorio GUI implementations.
If you are an user (not a mod creator/developer) you can read only the section 1, if instead you are a mod developer and you want understand if this mod fit your needs, see the section 2.

Summary, this is the standalone wiki version of Krastorio 2 wiki GUI.

1 - USERS GUIDE
If you are using a mod that use this library mod for provide a wiki to users, just simply install it, from the internal Factorio mod installer, or download it from the mod portal and place it in the mod folder of Factorio. Remember that you need at lease Factorio 0.18.13 o greater.

This is the list of know compatible mods:
- Krastorio2 (0.9.9. or greater)

2 - MODDERS GUIDE
Ok below I will describe how Booktorio works, let's start from the basic;
First, is recommended to add Booktorio in the optional dependencies, for be sure that when the remote calls will be called will already be available.
Booktorio is available to be called only in control phase, this is the available calls:

Code: Select all

remote.call("Booktorio", "add_thread", new_thread, not_override)

This call is the basic one to add a thread, the variable new_thread is a table defined as the pseudo-prototype thread(which we will see later). If not_override is false, nil or not specified then the basic action is override the old thread added.

Code: Select all

remote.call("Booktorio", "override_thread", new_thread)

This call is similar to add_thread, but will override for sure. This wrapper is more like for have more intelligible code.

Also is recommended to use a form like this for call the remote:

Code: Select all

if remote.interfaces["Booktorio"] then
	remote.call("Booktorio", "add_thread", new_thread) 
end

Because will avoid some errors in case that the mod is not present.
The suggested events where this remotes must be called are in on_init and on_configuration_changed.

Now let's see how to implement the wiki, so we must talk about how Booktorio load implement mod section.
For be simple implement a wiki, this mod defined some "pseudo-prototype", like Factorio use in the normal prototype definition is data phases. We have this kind of pseudo-prototype:
- Thread
- Topic
- TopicTitle
- TopicSubtitle
- TopicText
- TopicImage

Thread
This is the main object (a table) must be given to Booktorio in remotes, have the follow properties:
- name :: LocalisedString or string (mandatory)
- localized :: bool (optional)
- topics :: table of Topic (mandatory)
- specified_version :: uint8 (optional)

Mandatory values
- name, the name of this thread(mod section), can be localized.
- topics, a set of Topic object.

Optional values
- localized, specify if the property name should not be localized, set this to false if you don't want that the name string will be localized.
- specified_version, specify the version of this thread (via one unsigned integer), this can be useful for update the thread, if is called the remote interface "add_thread" with an existing thread, not_override = false or nil, but the specified_version is greater with the stored one, will be overrided anyway.

Topic
This is a single topic.
- name :: LocalisedString or string (mandatory)
- localized :: bool (optional)
- topic :: table of TopicTitle or TopicText or TopicImage (mandatory)
- align :: string (optional)

Mandatory values
- name, the name of this topic, can be localized, also this string is used in the left list for select the topic.
- topic, is a set of TopicTitle or TopicText or TopicImage, the can be defined all or only some of them in the same topic, only the TopicTitle can be defined one time, and must be positioned as first element of the table, or can be omitted, if the TopicTitle will be defined in positions different from the first will be skipped. Instead, TopicTexts or TopicImages, can be defined in any quantity and order.

Optional values
- localized, specify if the property name should not be localized, set this to false if you don't want that the name string will be localized.
- align, change the align of the topic, can have the follows values: "left", "center", "right".

TopicTitle
Is the title of the topic, must be the first element of the topic table.
- type :: string (mandatory)
- title :: LocalisedString or string (mandatory)
- localized :: bool (optional)

Mandatory values
- type, is the type of this element, in this case must be "title".
- title :: is the string of the title, can be localized.

Optional values
- localized, specify if the property title should not be localized, set this to false if you don't want that the name string will be localized.

TopicSubtitle
Show a subtitle, differently from the title, they can be more than one.
- type :: string (mandatory)
- subtitle :: LocalisedString or string (mandatory)
- localized :: bool (optional)

Mandatory values
- type, is the type of this element, in this case must be "text".
- subtitle, the text of the subtitle, can localized.

Optional values
- localized, specify if the property subtitle should not be localized, set this to false if you don't want that the name string will be localized.

TopicText
Show a text, can be multi-line.
- type :: string (mandatory)
- text :: LocalisedString or string (mandatory)
- localized :: bool (optional)

Mandatory values
- type, is the type of this element, in this case must be "text".
- text, the string to show, can be multi-line and localized.

Optional values
- localized, specify if the property text should not be localized, set this to false if you don't want that the name string will be localized.

TopicImage
Show a image, must be associated to a SpritePath.
- type :: string (mandatory)
- spritename :: name of SpritePath (mandatory)

Mandatory values
- type, is the type of this element, in this case must be "image".
- spritename, is the name of the SpritePath that must show this image element.

All TopicTitle, TopicSubtitle, TopicText, TopicImage, support pair definition, for exame this two are equivalent forms:

Code: Select all

	{type = "text", text = "gui.bk-ex-description-1"}
	{"text", "gui.bk-ex-description-1"}

Only if have the two main mandatory values defined.

---

Example

Code: Select all

-- Defining a new thread
local new_thread =
{
	name = {"gui.bk-ex-name"},
	specified_version = 0,
	topics =
	{
		{
			name  = {"gui.bk-ex-example-1"},
			topic =
			{	
				-- A title and a text, how you can see the localize string can be defined with or without brackets
				{type = "title", title = {"gui.bk-ex-title-1"}},
				{type = "text", text = "gui.bk-ex-description-1"},
				{type = "text", text = "Instead, this text is not localized", localized = false}
			}
		},
		{
			name  = {"gui.bk-ex-example-2"},
			topic =
			{	
				-- A image example, how you can see the image is specified from a name
				{type = "text", text = "This is an image example:", localized = false},
				{type = "image", spritename = "wikipedia-image-example"}
			}
		}
	}
}

You can download the Booktorio Example mod on the portal.
Also, you can test the code above using the Booktorio Example mod.

Requests
I accept suggestions for new wiki elements implementations, contact me on discord or open a discussion in the mod portal mod thread.
It's already planned to write more detailed documentation, anyway this is an initial release, many other features will be added in future.

This mod is part of mods developed by Krastorio Team

Factorio Forums

[MOD 0.18] Booktorio

[MOD 0.18] Booktorio