User:Raiguard/Tutorial:Modding tutorial/GUI: Difference between revisions

From Official Factorio Wiki
Jump to navigation Jump to search
(Initial stub page.)
 
(wrapped in nowiki tags to prevent redlinks)
 
(3 intermediate revisions by 2 users not shown)
Line 1: Line 1:
'''THIS PAGE IS A WORK-IN-PROGRESS.'''
<nowiki>'''THIS PAGE IS A WORK-IN-PROGRESS.'''


While you cannot edit base game GUIs, the Lua API includes the ability to create your own, completely custom GUIs. This tutorial will get you up to speed with creating such GUIs.
While you cannot edit base game GUIs, the Lua API includes the ability to create your own, completely custom GUIs. This tutorial will get you up to speed with creating such GUIs.
Line 5: Line 5:
== Before you Begin ==
== Before you Begin ==


Be sure you have the [https://lua-api.factorio.com/latest/LuaGui.html LuaGui], [https://lua-api.factorio.com/latest/LuaGuiElement.html LuaGuiElement], and https://lua-api.factorio.com/latest/LuaStyle.html LuaStyle] pages handy.
Be sure you have the [https://lua-api.factorio.com/latest/LuaGui.html LuaGui], [https://lua-api.factorio.com/latest/LuaGuiElement.html LuaGuiElement], and [https://lua-api.factorio.com/latest/LuaStyle.html LuaStyle] pages handy.


There are two in-game tools that are absolutely essential for creating GUIs:
=== Tutorial syntax ===


=== GUI border view ===
This tutorial will adapt some methods from [https://wiki.factorio.com/Tutorial:Modding_tutorial/Gangsir Modding tutorial/Gangsir], namely:
 
<pre style="background-color:#AAFFAA!important; color:black">
Code tinted green like this should be included into the mod this tutorial is going to create; If the reader follows along with it. The best way to do this is to copy and paste, to ensure faithful reproduction.
Whenever code is added to the mod, a Lua comment with the file name will be at the beginning of the green box. Place the code in the box into that file. Eg:
--control.lua
</pre>
 
<pre style="background-color:#DDA0DD!important; color:black">
Code tinted purple like this should not be included into the mod, it's just for educational/example purposes, and to boost understanding.
</pre>
 
For the purposes of the tutorial, it would be a good idea to create a fresh mod, separate from the mod you created in Gangsir's tutorial.
 
=== In-game tool: GUI border view ===


[[File:Modding tutorial Ctrl F5.png|500px]]
[[File:Modding tutorial Ctrl F5.png|500px]]
Line 15: Line 29:
Hitting '''Control + F5''' on your keyboard will bring up the "GUI border view". This surrounds all GUI elements with red borders, and can help you visualize how things are laid out.
Hitting '''Control + F5''' on your keyboard will bring up the "GUI border view". This surrounds all GUI elements with red borders, and can help you visualize how things are laid out.


=== GUI style inspector ===
=== In-game tool: GUI style inspector ===


[[File:Modding tutorial Ctrl F6.png]]
[[File:Modding tutorial Ctrl F6.png]]


Hitting '''Control + F6''' on your keyboard will allow you to use the "GUI style inspector". This allows you to view an element's style inheritances when you hover over it. Combined with the GUI border view, you can inspect normally hidden GUI elements.
Hitting '''Control + F6''' on your keyboard will allow you to use the "GUI style inspector". This allows you to view an element's style inheritances when you hover over it. Combined with the GUI border view, you can inspect normally hidden GUI elements.
=== Library: mod-gui ===
Add this require into your script file before you begin:
<pre style="background-color:#AAFFAA!important; color:black">
-- control.lua
local mod_gui = require("__core__.lualib.mod-gui")
</pre>


== The Root ==
== The Root ==


Every GUI must start in one of the five GUI "roots", listed in [https://lua-api.factorio.com/latest/LuaGui.html LuaGui]:
To build a GUI, you must gain access to the GUI "root". The most common method of access is through [https://lua-api.factorio.com/latest/LuaPlayer.html#LuaPlayer.gui LuaPlayer::gui]:
 
* '''top:''' Aligns the GUI at the top of the screen. Multiple elements will be flowed next to each other so they don't overlap.
* '''left:''' Aligns the GUI at the left of the screen. Multiple elements will be flowed next to each other so they don't overlap.
* '''center:''' Centers the GUI on the player's screen. Multiple elements will be flowed next to each other so they don't overlap.
* '''goal:''' Where the objective GUI sits. It is recommended not to use this root unless creating a scenario. Multiple elements will be flowed next to each other so they don't overlap.
* '''screen:''' An empty element that allows you to position your GUI anywhere on the player's screen. Because of this, multiple elements may overlap. Elements are placed in the top-left corner by default.


You will want to place your GUI in '''screen''', unless you have a specific reason not to.
<pre style="background-color:#AAFFAA!important; color:black">
-- control.lua
script.on_event(defines.events.on_player_created, function(event)
  local player = game.get_player(event.player_index)
  local player_gui = player.gui
end)
</pre>


== Adding elements ==
== Adding elements ==


'''TO BE CONTINUED...'''
'''TO BE CONTINUED...'''
</nowiki>

Latest revision as of 10:59, 9 April 2021

'''THIS PAGE IS A WORK-IN-PROGRESS.''' While you cannot edit base game GUIs, the Lua API includes the ability to create your own, completely custom GUIs. This tutorial will get you up to speed with creating such GUIs. == Before you Begin == Be sure you have the [https://lua-api.factorio.com/latest/LuaGui.html LuaGui], [https://lua-api.factorio.com/latest/LuaGuiElement.html LuaGuiElement], and [https://lua-api.factorio.com/latest/LuaStyle.html LuaStyle] pages handy. === Tutorial syntax === This tutorial will adapt some methods from [https://wiki.factorio.com/Tutorial:Modding_tutorial/Gangsir Modding tutorial/Gangsir], namely: <pre style="background-color:#AAFFAA!important; color:black"> Code tinted green like this should be included into the mod this tutorial is going to create; If the reader follows along with it. The best way to do this is to copy and paste, to ensure faithful reproduction. Whenever code is added to the mod, a Lua comment with the file name will be at the beginning of the green box. Place the code in the box into that file. Eg: --control.lua </pre> <pre style="background-color:#DDA0DD!important; color:black"> Code tinted purple like this should not be included into the mod, it's just for educational/example purposes, and to boost understanding. </pre> For the purposes of the tutorial, it would be a good idea to create a fresh mod, separate from the mod you created in Gangsir's tutorial. === In-game tool: GUI border view === [[File:Modding tutorial Ctrl F5.png|500px]] Hitting '''Control + F5''' on your keyboard will bring up the "GUI border view". This surrounds all GUI elements with red borders, and can help you visualize how things are laid out. === In-game tool: GUI style inspector === [[File:Modding tutorial Ctrl F6.png]] Hitting '''Control + F6''' on your keyboard will allow you to use the "GUI style inspector". This allows you to view an element's style inheritances when you hover over it. Combined with the GUI border view, you can inspect normally hidden GUI elements. === Library: mod-gui === Add this require into your script file before you begin: <pre style="background-color:#AAFFAA!important; color:black"> -- control.lua local mod_gui = require("__core__.lualib.mod-gui") </pre> == The Root == To build a GUI, you must gain access to the GUI "root". The most common method of access is through [https://lua-api.factorio.com/latest/LuaPlayer.html#LuaPlayer.gui LuaPlayer::gui]: <pre style="background-color:#AAFFAA!important; color:black"> -- control.lua script.on_event(defines.events.on_player_created, function(event) local player = game.get_player(event.player_index) local player_gui = player.gui end) </pre> == Adding elements == '''TO BE CONTINUED...'''