GIANTS Game Engine v9 Documentation

Table of Contents

1. Chapter 01: Overview
   1. Enable development controls
   2. Runtime development key short-cuts
   3. Console Command Reference
2. Chapter 02: Editor
   1. Viewport
   2. Scenegraph
   3. Attributes
   4. Toolbar
   5. Terrain
   6. User Attributes
   7. Scripting
   8. Terrain Editing
   9. Replace Dialog
   10. Interactive Placement
   11. Other functionality
   12. Key short-cuts
3. Chapter 03: Debugger
   1. GIANTS Debugger
   2. Overview of panels
   3. Creating a new project
   4. Global and local variables
   5. Callstack panel
   6. Running new scripts during debugging
   7. Breakpoints
   8. Game output
   9. Searching in code
   10. Shortcuts
4. Chapter 04: Scripting API Reference
   1. Script Reference(1.2.0.1)
      1. General
      2. Animation
      3. AI
      4. I3D
      5. Handtools
      6. Events
      7. Objects
      8. Placeables
      9. Triggers
      10. Utils
      11. Vehicles
      12. Specializations
      13. animals
      14. AnimalHusbandryModules
      15. shop
      16. collections
      17. densityMaps
      18. economy
      19. effects
      20. weather
      21. farms
      22. fieldJobs
      23. dialogs
      24. GUI
      25. materials
      26. misc
      27. missions
      28. modHub
      29. Player
      30. sounds
      31. trainSystem
      32. tutorials
      Engine Reference(8.0.0.0)
      1. General
      2. Entity
      3. Node
      4. Scenegraph
      5. Lighting
      6. Camera
      7. Shape
      8. Particle System
      9. Physics
      10. Spline
      11. Animation
      12. Overlays
      13. Sound
      14. Input
      15. XML
      16. Network
      17. Callbacks
      18. Text Rendering
      19. Terrain Detail
      20. Tire Track
      21. Editor
      22. AI
      23. Rendering
      24. String
      25. Math
      26. I3D
      27. Fillplanes
      28. ModDownloadManager
   2. Foundation Reference
      1. Scenegraph
      2. Input
5. Chapter 05: Tutorials
   1. Tutorial 1 - Load i3d files and basics
   2. Tutorial 2 - Light functions, global time and rendering text
   3. Tutorial 3 - User Attributes
   4. Tutorial 4 - Timers
   5. Tutorial 5 - Physics
   6. Tutorial 6 - Overlays
   7. Tutorial 7 - Audio
6. Chapter 06: Exporter
   1. Autodesk Maya¹ I3D Exporter
      1. Material Export Options
      2. Manual Installation
   2. Blender I3D Exporter
7. Chapter 07: Content Creation - Artwork Guide
   1. Autodesk Maya
   2. Texturing
8. Chapter 08: I3D Format
   1. Introduction
   2. Features
   3. Overview
   4. Specification
      1. General Layout
      2. Materials
      3. Shapes
      4. Dynamics
      5. Scenegraph
      6. Animation

Overview

Enable development controls

Runtime development key short-cuts

Console command reference

help

List all available commands

showFps

Show frames per second

enableFramerateLimit

Enable/disable frame per second limiter

framerateLimitFPS

Frame per second limit attribute

listEntities

Print detailed entity list

listResources

Print detailed resource list

parallelRenderingAndPhysics

Enable parallel rendering and physics

exit, quit or q

Quits application

Editor

Table of Contents

1. Viewport
2. Scenegraph Panel
3. Attributes Panel
4. Toolbar
5. Terrain Editing
6. User Attributes
7. Animation Panel
8. Particle System Panel
9. Spline Editing
10. Scripting
11. Replace Dialog
12. Interactive Placement
13. Other functionality
14. Keyboard short-cuts

Viewport

Navigation

View Options

Scenegraph Panel

Attributes Panel

Toolbar

• Create a new i3d file
• Open an existing i3d file
• Open i3d file in text editor
• Reload i3d file
• Save the i3d file
• Save i3d file as
• Import an i3d file

• Undo last action
• Redo last action

• Play/Stop

• Terrain Sculpt Mode
• Terrain Detail Texture Paint Mode
• Terrain Info Layer Paint Mode
• Terrain Foliage Paint Mode

• Reload all textures
• Reload textures of selected objects

• Open Script Editor

Terrain Editing

User Attributes

Animation Panel

Particle System Panel

Spline Editing

Scripting

Replace Dialog

Interactive Placement

Other functionality

Default keyboard short-cuts

Debugger

Table of Contents

1. GIANTS Debugger/IDE
2. Overview of panels
3. Creating a new project
4. Global and local variables
5. Callstack panel
6. Running new scripts during debugging
7. Breakpoints
8. Game output
9. Searching in code
10. Shortcuts

GIANTS Debugger/IDE

The GIANTS Debugger is a new tool for creating, editing and debugging script mods. It works as an editor and a “remote” debugger in one. It interacts with the game state and provides you with information about the game state.

Possible use-case scenarios:

• to create or modify LUA and XML files
• using breakpoints to see how script is executed
• investigating a paused game state by looking through callstack or inspecting variables
• seeing when and how variables change
• live-coding by writing script while the game is running

The Debugger can be used on all kinds of mod configurations. These are the most common three configurations:

Working on a single mod (fast iteration time, but only compatible with singeplayer):
Unzip your mod and put the mod in the “mods” directory (by default in Documents/My Games/FarmingSimulator2019/mods). Make sure that the layout of the mod is correct, i.e. the modDesc.xml is directly in the mod folder (i.e. mods//modDesc.xml). Then create a new project in the Debugger. In “Project Settings”, set “Mod Name” to be the same name as the name of the mod folder and set the “Mod Directory” as a path to the directory of the mod (mods/). In case the mod zip file is already in the “mods” directory remove the zip file for the “mods”, because the zip file has priority over the directory when the game is loading.

Working on multiple mods at the same time (fast iteration time, but only compatible with singeplayer):
Follow the instructions above, but when you create a project in the Debugger, set the “Mod Directory” to “mods” directory instead of the specific mod directory. This way you can edit several mods at the same time. In this configuration, the “Mod Name” is not important, you can call it anything you like.

Working on a single mod outside the “mods” directory (also compatible with multiplayer):
This is the most complex configuration, and it is the only one that lets you debug mods in multiplayer. Place the mod zip file in the “mods” directory and unzip it somewhere else. In “Project Settings” set the “Mod Name” to match with the name of the zip file but without .zip at the end) and set the “Mod Directory” as a path to the unzipped directory. For every change you make in the Debugger, you will have to re-create the mod zip file and copy it to the “mods” directory before you start the game. External tools for zipping are useful for this purpose (not included).

Overview of panels

• File Browser: view files and folders in your project directory
• Functions: list of functions defined in the current file
• Globals: view global variables
• Locals: view local variables
• Watch: view the values of user-defined variables
• Script console: run user-defined parts of code
• Callstack: view current callstack
• Breakpoints: manage breakpoints
• Output: view log output
• Find Results: view results from the Find in Files dialog

Creating a new project

First you need to open or create a project.

Most of the required parameters are self-explanatory. The “Mod Directory” can be a path to a single mod or a “mods” directory if you are working on several mods at the same time. If you are working on a single mod, the “Mod Name” must have the same name as the .zip file. The “User Profile App Directory” should be saved as a path to a folder where the game stores user data (changes are not needed by default if the game configuration has not been changed manually). The debugger uses sockets to communicate with the game and listens at the port defined as the “Debug Network Port”.

Global and local variables

The function of the “Globals” and “Locals” panels is the same: to explore the value of local and global variables at a current execution point (using breakpoints to halt execution and observe these variables, or by hitting the ‘break all’ button). By right-clicking on a variable, you can add it as a “Watch” or a “Breakpoint”.

The ”Watch” panel is similar to the “Globals” and “Locals” panel, but instead of global or local variables, you can select variables that you would like to ‘watch’. Values are updated every time a breakpoint is hit or when you execute the code step-by-step. Variable names can be written like most other simple Lua statements:

• variableName
• object.member
• table[1]
• table[index]
• table[object.index]

Callstack panel

The “Callstack” panel shows you the callstack at a current execution point. Double-click on a line to open a file at the location of the call. The Debugger even allows you step through some of the base game functions for which the source code has been made public. Grayed-out lines are parts of code that have not been made public.

Running new scripts during debugging

The “Script Console” executes user-defined Lua code when execution is paused (by hitting a breakpoint or break-all being pressed). Enter your code in the bottom part of the panel and press Ctrl + Enter to execute it.

Breakpoints

The “Breakpoints” panel is where you manage breakpoints.

Regular breakpoints can be placed in the code by clicking on the vertical gray bar on the left of the code panel. You can also use F9 to enable/disable a breakpoint at the current position. The program will stop running when it tries to execute a line with a breakpoint.

Data breakpoints can be placed by right-clicking on a variable name in the “Globals”/”Locals”/”Watch” panel or by right-clicking on a name in the text editor. A data breakpoint will be hit when the data for the specified variable changes.

You can fine-tune a breakpoint by adding a conditional expression and/or hit count condition to it. These conditions are evaluated each time a breakpoint is hit and the code will only stop executing once the conditions are met.

Game output

The “Output” panel shows the game’s log output. If a script error is reported, this panel will provide you with the file name and line number, so that you can double-click on it and view the code causing the error. The output is the same as the log file written by the game.

Searching in code

The “Find Results” panel shows search results from the “Find in Files” dialog. Double-clicking on a result opens a file at the search hit location.

The “Find Replace” window behaves in a similar way to other text editors. “Find” and “Replace” directly show the results in the text editor; while “Find in Files” searches through the entire file and shows results in the “Find Results” panel. Other search modes are available too:

• “Extended” search allows you to use special “escape” characters (\t = tab, \n = new line, \r = carriage return, \0 NULL character and \\ = backslash)
• “Regular Expression” searches with regular expressions. Captures are defined with brackets ‘(‘ and ‘)' in the search string and can be placed with $1-$9 in the replace string.

Default keyboard short-cuts

Scripting API Reference

Script Version: 1.2.0.1

AchievementMessage

Description

Achievement message display element.
-- Used to display a message in the HUD when a new achievement is unlocked.
--@category GUI

new

Create a new instance of AchievementMessage.

new(string hudAtlasPath, table inputManager, table guiSoundPlayer, ContextActionDisplay ContextActionDisplay)

onMenuVisibilityChange

Handle changes in menu visibility.
Keeps track of menu visibility state to avoid showing (or updating) an achievement message when the menu is active.

onMenuVisibilityChange()

showMessage

Show an achievement message.
The message will be shown as soon as the player is not in a menu and there is no context action display visible.
Messages will however not be checked for overlaps. The caller has to make sure that achievements are displayed
sequentially.

showMessage(string title, string description, string iconFilename, table iconUVs, float duration)

update

Update display state.

update()

beginShowMessage

Actually start showing the message when nothing is obstructing the view.

beginShowMessage()

hideMessage

Hide the message, including animation.
Also removes the acknowledgment input events.

hideMessage()

draw

Draw the achievement message if necessary.

draw()

storeScaledValues

Store scaled positioning, size and offset values.

storeScaledValues()

setScale

Set this element's scale.

setScale()

getBackgroundPosition

Get the position of the background element, which provides this element's absolute position.

getBackgroundPosition(scale Current, float width)

createBackground

Create the empty background overlay

createBackground()

createComponents

Create required display components.

createComponents()

createFrame

Create the message frame.

createFrame()

createIcon

Create the achievement icon.

createIcon()

AnimalScreen

Description

Animal Buying Screen.
AnimalScreen = {}

new

Constructor

new(table target, table metatable)

onOpen

Callback on open

onOpen()

onClose

Callback on close

onClose(table element)

onClickBack

Callback on click back

onClickBack()

onClickOk

Callback on click cancel

onClickOk()

BaseMission

Description

Input context name for identification, does not take care of proper context handling

new

Create a new base mission

new(string baseDirectory, table customMt, table missionCollaborators)

initialize

Initialize mission after instantiation.
Create complex members and call dependency methods in here so that mission instantiation cannot fail.

initialize()

createHUD

Create the in-game HUD display.

createHUD()

addHelpButtonText

Deprecated: Replaced by InputBinding:setActionEventText()

addHelpButtonText()

subscribeSettingsChangeMessages

Subscribe to relevant game settings changes.

subscribeSettingsChangeMessages()

subscribeGuiOpenCloseMessages

Subscribe to GUI notifications of opening and closing.

subscribeGuiOpenCloseMessages()

onBeforeMenuOpen

Handle a menu open event.

onBeforeMenuOpen()

onAfterMenuClose

Handle a menu closed event.

onAfterMenuClose()

registerActionEvents

Register required input action events.

registerActionEvents()

registerPauseActionEvents

Register action events for pause actions.
Event registration in this method is enclosed in an input binding registration context (InputBinding:beginActionEventsModification()).
Make sure that this is only called when all other registration-context altering code is done.

registerPauseActionEvents()

onPause

Input event for "pause".

onPause()

onConsoleAcceptPause

Input event for breaking pause on consoles.

onConsoleAcceptPause()

onToggleHelpText

Input event for "toggle help text".

onToggleHelpText()

onSwitchVehicle

Input event for "switch vehicle".

onSwitchVehicle(directionValue Numeric)

Binding

Description

Binding of input to actions.
--@category Input
--@xmlConfig binding#device Device ID, must match a value returned by engine function getGamepadId() or one of the
constants of InputDevice.DEFAULT_DEVICE_NAMES.

new

Create a new Binding instance.

new(action InputAction, deviceId ID, axisNames List, axisComponent Component, inputComponent Component, index Binding)

createFromXML

Create a new Binding instance from an XML element.

createFromXML(int xmlFile, string elementTag, bool isLocked)

saveToXMLFile

Save this binding to XML.

saveToXMLFile(xmlFile Input, elementTag Element)

updateData

Update a binding with a new input target.
Always use this method to change existing bindings or risk invalid state.

updateData(deviceId (New), axisNames List, inputComponent [optional])

updateInput

Update this binding's input state.

updateInput(inputValue Current)

setIsAnalog

Set this binding's analog input flag.

setIsAnalog()

setIndex

Set this binding's index and update internal state.

setIndex()

setActive

Set this binding's active state.
Only active bindings are updated and can trigger action events.

setActive()

setFrameTriggered

Set the frame trigger flag which shows if this binding has triggered an event this frame.

setFrameTriggered()

getFrameTriggered

Get the frame trigger flag which shows if this binding has triggered an event this frame.

getFrameTriggered()

setComboMask

Set and store the combo bit mask for this binding.
This is agnostic of the actually bound device because a binding can only map input on one specific device.

setComboMask(int comboMask)

getComboMask

Get the combo bit mask.

getComboMask()

hasCollisionWith

Check if there is a collision between this binding and another one.
Two bindings collide if they bind the same input on the same axes of the same device.

hasCollisionWith(otherBinding Other)

isAlternativeTo

Check if this binding is an alternative to another one on the same action.
Two bindings are alternatives if they bind different input on the same axis of the same device category to the same action.

isAlternativeTo(otherBinding Other)

clone

Create a new instance of Binding with the same state as this instance.

clone()

copyInputStateFrom

Copy binding input state from another binding.

copyInputStateFrom()

isSameSlot

Check if this binding occupies the same binding slot as another binding on the same action.

isSameSlot()

getOppositeAxisComponent

Get the opposite axis component for a given axis component.

getOppositeAxisComponent(axisComponent One)

getOppositeInputComponent

Get the opposite input component for a given input component.

getOppositeInputComponent(inputComponent One)

makeId

Make and assign a binding ID.

makeId()

needJapanesePlaystationButtonSwap

Determine if we need to swap buttons for Japanese Playstation controllers by their convention.

needJapanesePlaystationButtonSwap()

swapJapanesePlaystationButtons

Swaps buttons for Japanese Playstation controllers if contained in the given axis names.

swapJapanesePlaystationButtons(table axisNames)

toString

Get a string representation of this binding.

toString()

BitmapElement

Description

Display element for images.
-- Used layers: "image" for the display image.
--@xmlConfig GuiElement#offset string [optional] Position offset of the displayed image relative to this element's origin in reference resolution, defaults to [0, 0]. Format: "[x]px [y]px".

setImageColor

Set this element's image color.
Omitted (nil value) color values have no effect and the previously set value for that channel is used.

setImageColor(state GuiOverlay, r Red, g Green, b Blue, a Alpha)

setImageRotation

Set this element's image overlay's rotation.

setImageRotation(float rotation)

BoxLayoutElement

Description

Layout element which lays out child elements in regular rows or columns.
-- Exceptions are elements whose "layoutIgnore" property is true.
-- Used layers: "image" for a background image.
--@category GUI
--@xmlConfig GuiElement#alignmentX string [optional] Horizontal alignment of the layout, defaults to "left". Valid values are "left", "right" and "center".

getLayoutCells

Extract a flow / cell data table from this box layout's elements.

getLayoutCells(ignoreVisibility Visibility)

getLayoutSizes

Calculate layout sizes based on flow cell data.

getLayoutSizes()

getAlignmentOffset

Get the layout space starting position offset for elements based on flow dimensions and alignments.

getAlignmentOffset(flowSize Flow, flowLateralSize Total)

getElementAlignmentOffset

Calculate element offsets for margins and to counteract alignment updates in GuiElement.updateAbsolutePositions()

getElementAlignmentOffset(directionX Layout, directionY Layout)

applyCellPositions

Apply layout positions to all given cells' elements.

applyCellPositions(flowCells List, offsetStartX Layout, offsetStartY Layout, directionX Layout, directionY Layout, lateralFlowSizes List)

focusLinkCells

Link layout cells' elements for focus navigation.

focusLinkCells(flowCells List)

focusLinkChildElement

Link a child element to others for focus navigation

focusLinkChildElement(element Current, previousElement Element, firstElement First, lastElement Last)

invalidateLayout

Invalidate the layout, will reposition all elements and update focus navigation.

invalidateLayout(ignoreVisibility If)

getFocusTarget

Return the actual focus target when this box layout is being focused. This can be a previously focused element within
the layout (depends on rememberLastFocus attribute), a programmatically defined entry point based on the incoming
direction or simply the first layout element (when no other options apply).

getFocusTarget(incomingDirection Focus, moveDirection Actual)

ButtonElement

Description

Clickable button element.
-- Used layers: "image" for the background, "icon" for a button glyph.
-- All button UI callbacks do not require or provide any arguments.
--@category GUI
--@xmlConfig GuiElement#iconSize string [optional] Pixel size of button glyph in reference resolution. Format: "[width]px [height]px"

loadInputGlyphColors

Load glyph overlay colors.

loadInputGlyphColors(profile If, xmlFile If, key XML)

loadInputGlyph

Load the actual input glyph symbols to display if an input action is defined on the button.

loadInputGlyph()

setKeyboardMode

Set the keyboard mode flag.

setKeyboardMode()

setInputAction

Set the input action for the display glyph by name.

setInputAction()

setImageUVs

Set UV coordinates for the button background and/or icon.

setImageUVs()

getIsSelected

Determine if this button is selected

getIsSelected()

getIsHighlighted

Determine if this button is highlighted

getIsHighlighted()

getIconModifiedTextOffset

Get modified text offset including changes from icon position and dimensions.

getIconModifiedTextOffset(float textOffsetX, float textOffsetY)

getTextOffset

Get text offset from element position including modifications from icon.

getTextOffset()

getText2Offset

Get shadow text offset from element position including modifications from icon.

getText2Offset()

getIconSize

Get the current icon size in screen space.

getIconSize()

updateSize

Update size of element depending on content

updateSize()

ButtonOverlay

Description

Keyboard button display overlay.
-- Overlay type which displays a keyboard key button symbol.
--@category GUI

delete

Delete this button overlay.

delete()

setColor

Set this overlay's background color.

setColor(r Red, g Green, b Blue, a Alpha)

renderButton

Render this overlay with the given parameters.

renderButton(buttonText Text, posX Screen, posY Screen, height Button, alignment Text)

getButtonWidth

Get the total display width of this button overlay for a given button text and height

getButtonWidth()

CareerScreen

Description

Career Screen.
Displays available save game slots.
-- @field savegameList Save game list

setIsWaitingForSaveGameInfo

Set UI waiting state, which displays or hides a dialog that says to wait.

setIsWaitingForSaveGameInfo()

CharacterCreationScreen

Description

Character Selection Screen.

setCharacterIndex

Set the index of the character. Is turned into a player and body pair.

setCharacterIndex()

updateCharacterWithSettings

Update the character with the currently configured options.

updateCharacterWithSettings()

updateCharacter

Update the character to match given options. Only reloads object if needed.

updateCharacter()

loadCharacterFinished

Loading of the character object finished

loadCharacterFinished()

updateCharacterOptions

Update the existing character with options that can be changed

updateCharacterOptions()

setHatHairNodeVisibility

Set the visbility of the 'hat hair': special hair when wearing a hat

setHatHairNodeVisibility()

ChatDialog

Description

Multiplayer chat dialog
-- @field textElement User chat message input element

onMenuAxisUpDown

Handle menu up/down input.
Scrolls through the chat history.

onMenuAxisUpDown()

ChatWindow

Description

HUD chat window.
-- Displays chat messages.
--@category GUI

new

Create a new ChatWindow.

new(string hudAtlasPath)

setChatMessages

Set the chat message history reference for displaying.
The array is owned by the caller and must not be modified.

setChatMessages(table messages)

scrollChatMessages

Scroll chat messages by a given amount.

scrollChatMessages(int delta, int numMessages)

onMenuVisibilityChange

Handle menu visibility state change.

onMenuVisibilityChange()

update

Update element state.

update()

draw

Draw the chat window.

draw()

setScale

Set this element's UI scale.

setScale()

getBackgroundPosition

Get this element's base background position.

getBackgroundPosition(float uiScale)

storeScaledValues

Store scaled positioning, size and offset values.

storeScaledValues()

createBackground

Create the background overlay.

createBackground()

ColorPickerDialog

Description

Color Picker Dialog
-- Lets the player pick from a set of colors.
-- @field buttonTemplate Color button template which is cloned per color

setColors

Set colors after opening.

setColors(table colors, table defaultColor)

focusLinkColorButtons

Apply custom grid-based focus linking

focusLinkColorButtons()

setInitialFocus

Set the initial focus when entering this dialog.

setInitialFocus()

setCallback

Set the dialog callback.

setCallback()

onClickColorButton

Handle activation of a color button.

onClickColorButton()

ContextActionDisplay

Description

Player context action display element.
-- Displays information about the current interaction context. Includes action names and current input scheme button
glyphs.
--@category GUI

new

Create a new instance of ContextActionDisplay.

new(string hudAtlasPath)

setContext

Sets the current action context.
This must be called each frame when a given context is active. The highest priority context is displayed or the one
which was set the latest if two or more contexts have the same priority.

setContext(string contextAction, string contextIconName, string targetText, int priority, string actionText)

update

Update the context action display state.

update()

resetContext

Reset context state after drawing.
The context must be set anew on each frame.

resetContext()

draw

Draw the context action display.

draw()

setScale

Set the scale of this element.

setScale()

storeScaledValues

Store scaled positioning, size and offset values.

storeScaledValues()

getBackgroundPosition

Get the position of the background element, which provides this element's absolute position.

getBackgroundPosition(scale Current, float width)

createBackground

Create an empty background overlay as a base frame for this element.

createBackground()

createComponents

Create display components.

createComponents(string hudAtlasPath, table inputDisplayManager)

createInputGlyph

Create the input glyph element.

createInputGlyph()

createFrame

Create the context display frame.

createFrame()

createActionIcons

Create action context icons.
Only one of these will be visible at any time.

createActionIcons()

ControlsController

Description

Controls settings controller.
-- Handles the input controls model and control logic for settings screen controls pages.
--@category GUI

new

Create a new ControlsController instance.

new()

setMessageCallback

Set a callback for displaying status messages.
Callback signature: messageCallback(messageId, additionalText, addLine)

setMessageCallback(messageCallback A)

setInputDoneCallback

Set a callback to react on input capture completion.
Callback signature: inputDoneCallback(madeChange)

setInputDoneCallback(inputDoneCallback A)

createDisplayAction

Create a display action for displaying from bindings for a given axis direction.

createDisplayAction(deviceCategory Device, actionBinding Action, isAxisPositive If)

getDeviceCategoryActionBindings

Get available action bindings per device category, including current changes (even before saving).

getDeviceCategoryActionBindings(deviceCategory Device)

getMouseAxisDisplayText

Get display text for a single mouse axis.

getMouseAxisDisplayText()

getGamepadAxisDisplayText

Get display text for a single gamepad axis.

getGamepadAxisDisplayText()

getBindingInputDisplayText

Get display text for input axis names of a binding.

getBindingInputDisplayText(Binding Binding)

saveChanges

Save changed bindings to user configuration.

saveChanges()

discardChanges

Discard any previously made binding changes.

discardChanges()

loadBindings

Load action input bindings.

loadBindings()

onClickInput

Handles clicking an input binding button for a given device category and action.

onClickInput(deviceCategory Input, bindingId ID, actionBinding Action)

beginWaitForInput

Begin waiting for input.
Overrides the global input hooks keyEvent() and mouseEvent() as well as the global update() loop, depending on which
device is being scanned. Also see InputBinding:startInputCapture().

beginWaitForInput(deviceCategory Category, bindingIndex Binding, DisplayActionBinding DisplayActionBinding)

onAbortInputGathering

Input gathering abort event.

onAbortInputGathering()

onDeleteInputBinding

Input gathering binding deletion event.

onDeleteInputBinding(DisplayActionBinding DisplayActionBinding, gatheringState {binding=DisplayActionBinding)

onCaptureKeyboardInput

Input gathering keyboard input event.

onCaptureKeyboardInput(keyName Key, isModifier True, inputValue 1, gatheringState {binding=DisplayActionBinding)

onCaptureMouseInput

Input gathering mouse input event.

onCaptureMouseInput(inputAxisName Mouse, isModifier True, inputValue Input, gatheringState {binding=DisplayActionBinding)

onCaptureGamepadInput

Input gathering gamepad / controller event.

onCaptureGamepadInput(deviceId Device, inputAxisName Axis, isModifier True, inputValue Input, gatheringState {binding=DisplayActionBinding)

endWaitForInput

Stop waiting for input.
Lifts the input override and notifies the screen listener.

endWaitForInput(madeChange If)

lockInput

Lock all UI input after capturing a new binding.

lockInput()

deleteBinding

Delete a binding from its action binding table.

deleteBinding()

assignKeyboardBinding

Assign a (new) keyboard input binding.

assignKeyboardBinding(DisplayActionBinding DisplayActionBinding, bindingIndex Binding, keyames List)

validateMouseCombo

Check if the given axis names contain a supported mouse combo.

validateMouseCombo()

assignMouseBinding

Assign a (new) mouse input binding.

assignMouseBinding(DisplayActionBinding DisplayActionBinding, inputAxisNames List, inputDirection Numeric)

assignGamepadBinding

Assign a (new) gamepad / controller input binding.

assignGamepadBinding(DisplayActionBinding DisplayActionBinding, bindingIndex Binding, deviceId Gamepad, inputAxisNames List, inputDirection Numeric)

assignBinding

Assign a (new) binding.
First tries to update an existing binding. If no binding with the given parameters exists to be updated, a new
binding is created instead, unless this would lead to an number of alternative bindings exceeding the maximum.

assignBinding(deviceId Binding, displayAction Cloned, bindingIndex Intended, inputAxisNames List, isPositiveAxis If, inputDirection Numeric, previousDeviceId [optional])

loadDefaultSettings

Load default input binding settings from the game's profile template.
Handle with care, this will overwrite all the player's input binding settings.

loadDefaultSettings()

DataGrid

Description

Creating data grid

new

@param table customMt custom metatable

new()

delete

Deletes data grid

delete()

getValue

@param integer colIndex index of column

getValue()

setValue

@param integer colIndex index of column

setValue(table value)

DepthOfFieldState

Description

Depth of field shader state.
-- This class wraps the depth of field shader parameter calls to allow convenient setting and resetting a specific
shader parameter state.
--@category GUI

new

Create a new depth of field state.
This will record the currently set parameters which are restored when calling reset().

new(float nearCoCRadius, float nearBlurEnd, float farCoCRadius, float farBlurStart, float farBlurEnd)

recordState

Record the current shader parameters for reset.
This is called on instantiation. If another state should be recorded, call this again afterwards.

recordState()

setParameters

Set one or more parameters after instantiation.
If any of the parameters is omitted, the currently stored value is used.

setParameters(float nearCoCRadius, float nearBlurEnd, float farCoCRadius, float farBlurStart, float farBlurEnd)

apply

Apply shader parameters which were provided on instantiation.

apply()

reset

Reset the shader parameters to the state they were in when this object had been created.

reset()

createFullscreenBlur

Create a depth of field state for a full screen blur effect.

createFullscreenBlur()

DirectSellDialog

Description

Vehicle selling or customization dialog
-- Opened when activating vehicle selling points.
-- @field headerText Dialog header text element

new

Create a new DirectSellDialog instance.

new(table target, table custom_mt, table shopConfigScreen, table messageCenter)

onClickOk

Handle "sell" button event.

onClickOk()

onClickActivate

Handle "customize" button event.

onClickActivate()

DisplayActionBinding

Description

Holds information about an action binding for display purposes.
-- This class is used to transfer input binding information between ControlsController and UI components.
--@category Input

new

Creates a new DisplayActionBinding.

new(action InputAction, isPositive If, displayName Display, Binding Bindings)

setBindingDisplay

Set display information for binding.

setBindingDisplay(Binding Binding, text Binding, column Display)

EditFarmDialog

Description

Farm edit and create dialog.
-- Lets a player edit a farm's properties or create a new farm.
-- @field buttonTemplate Color button template which is cloned per color

new

Create a new instance of EditFarmDialog.

new(table target, table custom_mt, table l10n, table farmManager)

setExistingFarm

Set existing farm ID whose properties are to be modified.
If no farm ID is given, a new farm will be created.

setExistingFarm()

storeAvailableColors

Find available farm colors and store them in fields.

storeAvailableColors()

onClickColorButton

Handle activation of a color button.
Shadows parent method which exits the dialog right away.

onClickColorButton()

onClickActivate

Handle dialog confirmation click / activation.
Depending on the mode, this will create a new farm or update an existing one.

onClickActivate()

Farm

Description

Permission types.

merge

Merge another farm into this farm. Used for creating an SP game from an MP game. (this is mutating)

merge(table other)

getFarmhouse

Get the farmhouse associated with the farm.

getFarmhouse()

getSpawnPoint

Get the spawnpoint associated with the farm(house).

getSpawnPoint()

getSleepCamera

Get the sleep camera.

getSleepCamera()

getActiveUsers

Get a list of active users. Useful for using their connection ID

getActiveUsers()

isUserFarmManager

Determine if a user is a manager of this farm.

isUserFarmManager(userId User)

getUserPermissions

Get the farm permissions of a user.

getUserPermissions(userId User)

setUserPermission

Set a user's permission in this farm.

setUserPermission(userId User, string permission, bool hasPermission)

promoteUser

Promote a user to farm manager.

promoteUser()

demoteUser

Demote a user from farm manager.

demoteUser()

setIsContractingFor

Update contracting status

setIsContractingFor(noSendEvent boolean)

changeBalance

Add or remove money from the farm

changeBalance(number amount)

getBalance

Get the current account balance of the farm.

getBalance()

getLoan

Get the current loan of the farm.

getLoan()

getHandTools

Get a list of filenames for accessible handtools

getHandTools()

addUser

Add a new user to the farm. This adds it to the players and active players list.
And also gives default permissions.

addUser()

removeUser

Remove a user from the farm.

removeUser()

onUserJoinGame

Called when a user joins the game. Active users is updated, and for spectator.
a new user might be added. Server only.

onUserJoinGame()

onUserQuitGame

Called when a user quits the game. The active user list is updated. Server only.

onUserQuitGame()

FarmManager

Description

Multiplayer

new

Creating manager

new()

loadMapData

Load data on map load

loadMapData()

unloadMapData

Unload data on mission delete

unloadMapData()

saveToXMLFile

Write field mission data to savegame file

saveToXMLFile(string xmlFilename)

loadFromXMLFile

Load fieldjob data from xml savegame file

loadFromXMLFile(string filename)

mergeFarmlandsForSingleplayer

Second step of merging: transfer all lands to the singleplayer farm

mergeFarmlandsForSingleplayer()

mergeObjectsForSingleplayer

Third step of merging: move vehicles and bales to singleplayer farm

mergeObjectsForSingleplayer()

delete

Deletes field mission manager

delete()

update

Updates field mission ownage data from xml savegame file

update(string filename)

getFarmForUniqueUserId

Get farm for given userId. To be used when player is not in the game

getFarmForUniqueUserId()

getFarmByUserId

Get farm for given userId. To be used when player is in the game.

getFarmByUserId()

updateFarms

On client, update the list of farms and set farm for given farmId

updateFarms()

getFarms

Get the array of known farms.
Callers should not modify this array.

getFarms()

transferMoney

Transfer an amount of money from the current user's farm to a destination farm.
Triggers a network event which checks farm balances and applies the change. Successful execution requires the current
user to have permission to transfer money as well as their current farm to have a sufficient balance.

transferMoney()

removeUserFromFarm

Remove player from their farm. Only works if the caller has permission (master user, farm manager)

removeUserFromFarm()

removeFarm

Farm has been destroyed. Remove from lists

removeFarm()

FieldInfoDisplay

Description

HUD field information display element.
-- Displays dynamic information about the field which the player is currently standing in (or close by).
--@category GUI

new

Create a new instance of FieldInfoDisplay.

new(string hudAtlasPath)

setupRows

Set up rows data structures.

setupRows()

setPlayer

Set the local player reference.

setPlayer()

setFruitType

Set the current fruit type to display.

setFruitType(int fruitTypeIndex, int fruitGrowthState)

setOwnerFarmId

Set the field owner

setOwnerFarmId(int ownerFarmId)

setFertilization

Set the fertilization factor info to display.

setFertilization(float fertilizationFactor)

setWeed

Set the weed factor info to display.

setWeed(float fertilizationFactor)

setPlowingRequired

Set the plowing required display.

setPlowingRequired(bool isRequired)

setLimeRequired

Set the lime required display.

setLimeRequired(bool isRequired)

addCustomText

Add a custom text row.
The custom text will be added in order of calls to this function after the default information.

addCustomText(string leftText, string rightText, table leftColor)

clearCustomText

Clear a custom text row previously added by FieldInfoDisplay:addCustomText().

clearCustomText(int rowIndex)

clearInfoRow

Clear a single info row's data.

clearInfoRow()

clearFieldData

Clear all previously set field data.
This does not clear custom text rows, which need to be cleared specifically using clearCustomText().

clearFieldData()

onFieldDataUpdateFinished

Called when FSDensityMapUtil.getFieldStatusAsync() in update() has finished.

onFieldDataUpdateFinished(table data)

updateSize

Update the info display size depending on used rows.

updateSize()

draw

Draw the display.

draw()

drawText

Draw text parts of this display element.

drawText()

getBackgroundPosition

Get the scaled background position.

getBackgroundPosition()

setScale

Set this element's UI scale factor.

setScale(float uiScale)

storeScaledValues

Store scaled position and size values.

storeScaledValues()

createBackground

Create the background overlay.

createBackground()

createComponents

Create required display components.

createComponents()

createFrame

Create the background frame element.

createFrame()

createRowListContainer

Create row list container.

createRowListContainer()

createSeparators

Create row separators.

createSeparators()

FillLevelsDisplay

Description

Vehicle HUD fill levels display element.
-- Displays fill level bars for the current vehicle configuration
--@category GUI

new

Creates a new FillLevelsDisplay instance.

new(string hudAtlasPath)

setVehicle

Set the currently controlled vehicle which provides display data.

setVehicle(table vehicle)

updateFillLevelBuffers

Update fill levels data.

updateFillLevelBuffers()

updateFillLevelFrames

Update fill level frames display state.

updateFillLevelFrames()

update

Update the fill levels state.

update()

draw

Draw this element.

draw()

setScale

Set this element's scale.

setScale()

getBackgroundPosition

Get the position of the background element, which provides this element's absolute position.

getBackgroundPosition(scale Current, float width)

storeScaledValues

Calculate and store scaling values based on the current UI scale.

storeScaledValues()

createBackground

Create an empty background overlay as a base frame for this element.

createBackground()

refreshFillTypes

Refresh fill type data and elements.

refreshFillTypes(table fillTypeManager)

createFillTypeFrames

Create fill type frames for all known fill types.

createFillTypeFrames()

createFillTypeFrame

Create a fill type frame for the display of a fill type level state.

createFillTypeFrame()

createFillTypeIcon

Create an icon for a fill type.

createFillTypeIcon()

createFillTypeBar

Create a fill type bar used to display a fill level.
The newly created bar is added to the given parent frame and an internal collection indexable by fill type index.

createFillTypeBar(string hudAtlasPath, table frame, float baseX, float baseY, table fillType)

FocusManager

Description

The FocusManager controls which element in the menu system is currently focused
and allows menu control with only keyboard or gamepad.
For each participating gui element the focus state and the next focused gui element
in each direction is stored. This data is set up directly in the xml file of the gui screen
and loaded through the loadElementFromXML() function or manually loaded within code by using
the loadElementFromCustomValues() method.
Focus handling is independent for every screen in the GUI. To swap screens the setGui() method
has to be used.
The focus system is then controlled with 5 actions: MENU_UP, MENU_DOWN, MENU_RIGHT and MENU_LEFT to
change the currently focused element in the specified direction and MENU_ACCEPT to activate
the currently focused element.
-- When using dynamically changing objects which cannot be set directly in the XML file of the screen
the method createLinkageSystemForElements() can be used to set up direction links between the
passed elements automatically.
--@category GUI

setGui

Set the active GUI for focus input.

setGui(Gui Screen)

getElementById

Get a focusable GuiElement in the current view by its ID.

getElementById()

getFocusedElement

Get the currently focused GuiElement

getFocusedElement()

serveAutoFocusId

Get a new automatic focus ID.
It's based on a simple integer increment and will be unique unless billions of elements require an ID.

serveAutoFocusId()

loadElementFromXML

Load GuiElement focus data from its XML definition.
This is called at the end of GuiElement:loadFromXML().

loadElementFromXML()

loadElementFromCustomValues

Add an element to the focus system with custom values.
The caller should ensure that explicitly set focus IDs are unique. If a duplicate ID is encountered, only the first
element with that focus ID is considered for focusing. The method returns a boolean value to indicate any problems
with data assignment. Callers can evaluate the value to check if the given parameters were valid. If in doubt or
when no elaborate focus navigation is needed, rely on automatic focus ID generation by omitting the ID parameter
(or set it to nil).

loadElementFromCustomValues(element Element, focusId Focus, focusChangeData Custom, focusActive If, isAlwaysFocusedOnOpen If)

removeElement

Remove a GuiElement from the current focus context.

removeElement()

linkElements

Links an element's focus navigation to another element for a given direction.
The link is unidirectional from source to target. If bi-directional links are desired, call this method again with
swapped arguments.

linkElements(sourceElement Source, direction Navigation, targetElement Target)

inputEvent

Handles input and changes focus if required and possible.

inputEvent(action Name, value Input, eventUsed Usage)

getDirectionForAxisValue

Get a direction value for a given menu input action and value

getDirectionForAxisValue()

isFocusInputLocked

Checks if the focus manager has an input lock on input.

isFocusInputLocked(inputAxis InputAction, value Axis, True if)

lockFocusInput

Locks a given input axis action's input for a time. Until the delay has passed, the focus manager will not react to
that input.

lockFocusInput(inputAxis InputAction, delay Delay, value Axis)

releaseMovementFocusInput

Release a focus movement input lock on an action.
Called by the UI input handling code. Avoid calling this for anything else.

releaseMovementFocusInput(action Focus)

resetFocusInputLocks

Reset all locks of focus input.

resetFocusInputLocks()

getClosestPointOnBoundingBox

Given a point and bounding box, get the closest other point on the bounding box circumference. If the point lies
within the bounding box, it is returned unchanged.

getClosestPointOnBoundingBox(x Point, y Point, boxMinX Bounding, boxMinY Bounding, boxMaxX Bounding, boxMaxY Bounding)

getShortestBoundingBoxVector

Calculate the shortest connecting line segment between two bounding boxes. Overlapping boxes will result in flipped
directions, so take care.

getShortestBoundingBoxVector()

checkElementDistance

Checks the distance between two GuiElements with the aim of incrementally finding the closest other element in a
direction within a screen view.

checkElementDistance(curElement Current, other Other, dirX Scan, dirY Scan, curElementOffsetY Position, closestOther Previously, closestDistanceSq Squared)

getNextFocusElement

Find the next other element to the one provided in a given navigation direction

getNextFocusElement(element GUI, direction Direction)

getNestedFocusTarget

Get an element's focus target at the deepest nesting depth, e.g. when multiple nested layouts point down to their
child elements until only a single element is left which points to itself.

getNestedFocusTarget(element GuiElement, direction Focus)

updateFocus

Update the current focus target.

updateFocus(element GuiElement, isFocusMoving Only, direction Focus, updateOnly If)

setHighlight

Activate a highlight on an element. Highlighted elements are only visually marked and do not receive focus activation.
Only one element will be highlighted at any time, usually corresponding to the current mouse over target.

setHighlight(element Element)

unsetHighlight

Remove highlight status from an element.

unsetHighlight(element Highlighted)

setFocus

Set focus on a GuiElement or its focus target.
Applies overlay state and triggers onFocusEnter() on the target.

setFocus(element Element, direction Focus, ... Variable)

unsetFocus

Removes focus from an element.
Applies overlay state and triggers onFocusLeave() on the target.

unsetFocus(element Element, ... Variable)

setElementFocusOverlayState

Set an elements focus overlay state for displaying.

setElementFocusOverlayState(element Target, isFocus If, handlePreviousState [optional])

requireLock

Globally lock focus input.

requireLock()

releaseLock

Release the global focus input lock.

releaseLock()

isLocked

Check if focus input is locked.

isLocked()

isDirectionLocked

Determine if focus navigation in a given direction is currently locked.

isDirectionLocked(direction Navigation)

hasFocus

Determine if a GuiElement is currently focused.

hasFocus()

getFocusOverrideFunction

Get a closure override function for elements' getFocusOverride() methods.

getFocusOverrideFunction(forDirections List, substitute Element, useSubstituteForFocus (Optional))

FrameElement

Description

Base display frame element. All GUI views (partial and full screen) inherit from this.
-- This element provides the functionality to register control IDs, which are then exposed as fields of the concrete
descendant class (e.g. MainScreen or PasswordDialog). The control IDs must be assigned verbatim to any control
in the corresponding configuration XML file. If a registered ID is not used, the field will not be assigned and
access will fail. Available field IDs are documented as field properties per class. When creating a new view, take
care to include the call to registerControls() in the constructor to declare and expose control elements as fields.
--@category GUI

clone

Override of GuiElement:clone().
Also exposes registered control element fields.

clone()

copyAttributes

Override of GuiElement:copyAttributes().
Also resets registered control IDs so they can be exposed as fields again.

copyAttributes()

getRootElement

Get the frame's root GuiElement instance.
This is the first and only direct child of a FrameElement, as defined by the GUI instantiation logic. This method
will always return a GuiElement instance, even if a new one must be created first.

getRootElement()

registerControls

Register a collection of control IDs for direct access in GUI views.

registerControls(controlIDs Table)

exposeControlsAsFields

Adds registered controls as fields to this FrameElement instance.
Called by the GUI system after loading.
The new fields will have the same name as the registered ID, so make sure there are no collision to avoid overrides
and that IDs are also valid as identifiers in Lua. If a control has been registered but no corresponding element is
available (e.g. when sub-classing and omitting some elements), the field will remain undefined. It's up to callers
to ensure that field configuration and usage in views matches.

exposeControlsAsFields(viewName View)

disableInputForDuration

Set input disabling to a given duration.

disableInputForDuration(float duration)

isInputDisabled

Check if input is currently disabled.

isInputDisabled()

setChangeScreenCallback

Set a callback for requesting a view change from within a frame or screen view.

setChangeScreenCallback(func callback)

setInputContextCallback

Set a callback function for requesting a custom menu input context for this frame.

setInputContextCallback(func callback)

setPlaySampleCallback

Set a callback function for requesting to play a sound sample.

setPlaySampleCallback(func callback)

changeScreen

Request a view change via the callback defined by setChangeScreenCallback().

changeScreen(table targetScreenClass)

toggleCustomInputContext

Request toggling of a custom menu input context for this frame via the callback defined by setInputContextCallback().

toggleCustomInputContext(bool isContextActive, string contextName)

playSample

Request playing a sound sample identified by name.

playSample(string sampleName)

FSBaseMission

Description

(Un)loading stations

initialize

Initialize mission after instantiation.
Create complex members and call dependency methods in here so that mission instantiation cannot fail.

initialize()

setHarvestScaleRatio

Sets harvest ratios for fertilizer, plow, lime and weed factor

setHarvestScaleRatio(float sprayRatio, float plowRatio, float limeRatio, float weedRatio)

getHarvestScaleMultiplier

Get harvest multiplier based on fertilizer, plow, lime and weed factor, 1 = best

getHarvestScaleMultiplier(integer fruitTypeIndex, float sprayFactor, float plowFactor, float limeFactor, float weedFactor)

updateMenuAccessibleVehicles

Check which vehicles are accessible and notify the menu.

updateMenuAccessibleVehicles()

addOwnedItem

Add an item to the owned items collection.
Also notifies the shop.

addOwnedItem()

removeOwnedItem

Remove an item from the owned items collection.
Also notifies the shop.

removeOwnedItem()

addLeasedItem

Add an item to the leased items collection.
Also notifies the shop.

addLeasedItem()

removeLeasedItem

Remove an item from the leased items collection.
Also notifies the shop.

removeLeasedItem()

updatePauseInputContext

Set or revert the pause input context based on current state.

updatePauseInputContext()

updateSaving

Update saving process.
Notifies the UI to display dialogs.

updateSaving()

onYesNoSavegameSelectDevice

Savegame device selection confirmation dialog response callback.

onYesNoSavegameSelectDevice()

onSaveGameUpdateComplete

Savegame overwrite completion callback.

onSaveGameUpdateComplete(int errorCode)

onYesNoSavegameOverwrite

Savegame overwrite confirmation dialog response callback.

onYesNoSavegameOverwrite()

showAttachContext

Display vehicle attachment context information for the current frame.

showAttachContext()

showTipContext

Display vehicle tipping context information for the current frame.

showTipContext()

showFuelContext

Display vehicle refueling context information for the current frame.

showFuelContext()

showFillDogBowlContext

Display dog companion food bowl fill context information for the current frame.

showFillDogBowlContext()

getMoney

Get money for farm or current player farm

getMoney(farmId integer)

getHasPlayerPermission

Get whether the current player has given permission.

getHasPlayerPermission(string permission, table connection, integer farmId, boolean checkClient)

getIngameMap

Get the in-game map rendering component.
Should only be used for UI.

getIngameMap()

startSaveCurrentGame

Start saving the game.

startSaveCurrentGame(bool isDediSaving)

saveSavegame

Actually save the game locally.

saveSavegame()

getDoghouse

Returns a doghouse

getDoghouse(integer farmId)

registerHusbandry

Register a husbandry in the mission.

registerHusbandry()

unregisterHusbandry

Unregister a husbandry in the mission.

unregisterHusbandry()

getVehicleName

Extract a concrete vehicle's display name from its store data.

getVehicleName(table vehicle)

registerActionEvents

Register required input action events.

registerActionEvents()

registerPauseActionEvents

Register action events for pause actions.
Event registration in this method is enclosed in an input binding registration context (InputBinding:beginActionEventsModification()).
Make sure that this is only called when all other registration-context altering code is done.

registerPauseActionEvents()

onToggleMenu

Input event for "open menu".

onToggleMenu()

onToggleStore

Input event for "open shop".

onToggleStore()

toggleChat

Toggle chat display.
Called from input to open the chat dialog and from the chat dialog to close it again.

toggleChat()

onToggleRadio

Input event for "toggle radio".

onToggleRadio()

onChangeTimescale

Input event for "increase timescale" and "decrease timescale"

onChangeTimescale()

onShowHelpIconsChanged

Handle a settings change for showing help icons.

onShowHelpIconsChanged()

onRadioVehicleOnlyChanged

Handle a settings change for the radio vehicle only setting.
If the current radio state is active, the radio will start playing if the context fits (e.g. turn to global, and
player is on foot).

onRadioVehicleOnlyChanged()

onRadioIsActiveChanged

Handle a settings change for the radio active state.

onRadioIsActiveChanged()

setRadioActionEventsState

Set the active state for the radio action events.

setRadioActionEventsState()

subscribeMessages

Subscribe to FS-specific event messages.
The BaseMission parent class unsubscribes from messages in delete(). No clean-up required in sub-classes like this.

subscribeMessages()

notifyPlayerFarmChanged

Handle a local client changing the farm.

notifyPlayerFarmChanged()

GameInfoDisplay

Description

HUD general game information display.
-- Displays current game information. This includes weather, current account balance and time settings.
--@category GUI

new

Create a new instance of GameInfoDisplay.

new(string hudAtlasPath)

setMoneyUnit

Set the money unit for displaying the account balance.

setMoneyUnit(int moneyUnit)

setMissionStats

Set the MissionStats reference for displaying information.

setMissionStats(table missionStats)

setMissionInfo

Set the mission information reference for base information display.

setMissionInfo(table missionInfo)

setEnvironment

Set the environment reference to use for weather information display.

setEnvironment(table environment)

setMoneyVisible

Set visibility of the money display.

setMoneyVisible()

setTimeVisible

Set visibility of time display.

setTimeVisible()

setTemperatureVisible

Set visibility of temperature display.

setTemperatureVisible()

setWeatherVisible

Set visibility of weather display.

setWeatherVisible()

setTutorialVisible

Set visibility of tutorial progress display.

setTutorialVisible()

setTutorialProgress

Set the current tutorial progress values.

setTutorialProgress(float progress)

update

Update the game info display state.

update()

updateTime

Update time display.

updateTime()

updateTemperature

Update temperature display.

updateTemperature()

updateWeather

Update weather display

updateWeather()

getVisibleWidth

Get the game info display's width based on its visible info boxes.

getVisibleWidth()

updateSizeAndPositions

Update sizes and positions of this elements and its children.

updateSizeAndPositions()

draw

Draw the game info display.

draw()

drawMoneyText

Draw the text part of the money display.

drawMoneyText()

drawTimeText

Draw the text part of the time display.

drawTimeText()

drawTemperatureText

Draw the text part of the temperature display.

drawTemperatureText()

drawTutorialText

Draw the text part of the tutorial progress display.

drawTutorialText()

animateWeatherChange

Make an animation for a weather change.

animateWeatherChange()

addActiveWeatherAnimation

Animate a weather icon becoming active.

addActiveWeatherAnimation()

addInactiveWeatherAnimation

Animate a weather icon becoming inactive.

addInactiveWeatherAnimation()

addBecomeCurrentWeatherAnimation

Animate a weather icon becoming the current weather icon.

addBecomeCurrentWeatherAnimation()

addWeatherPositionAnimation

Animate weather icon position changes.

addWeatherPositionAnimation()

getBackgroundPosition

Get this element's base background position.

getBackgroundPosition(float uiScale)

setScale

Set this element's UI scale factor.

setScale(float uiScale)

storeScaledValues

Store scaled positioning, size and offset values.

storeScaledValues()

createBackground

Create the background overlay.

createBackground()

createComponents

Create required display components.
Also adds a separator HUDElement instance as a field (".separator") to all info boxes.

createComponents()

createMoneyBox

Create the money display box.

createMoneyBox()

createTimeBox

Create the time display box.

createTimeBox()

createTemperatureBox

Create the temperature display box.

createTemperatureBox()

createWeatherBox

Create the weather display box.

createWeatherBox()

createWeatherIcon

Create a weather icon for current and upcoming weather conditions.

createWeatherIcon(string hudAtlasPath, int weatherId, float boxHeight, table uvs, table color)

createTemperatureIcon

Create a temperature icon to display stable or changing temperatures.

createTemperatureIcon(string hudAtlasPath, float leftX, float bottomY, float boxHeight, table uvs, table color)

createClockHand

Create a rotatable clock hand icon element.

createClockHand(string hudAtlasPath, float posX, float posY, table size, table uvs, table color, table pivot)

createTimeScaleArrow

Create a time scale arrow icon element.

createTimeScaleArrow(string hudAtlasPath, float posX, float posY, table size, table uvs)

createVerticalSeparator

Create and return a vertical separator element.

createVerticalSeparator()

createTutorialBox

Create the tutorial progress box.

createTutorialBox()

GamepadSigninScreen

Description

Sign-In Screen before Main Menu.
-- Used in console version.
-- @field startText Button prompt text to start the game.

inputEvent

GUI input event callback.
See GuiElement:inputEvent().

inputEvent()

signIn

Event function for button sign in.

signIn()

GamePausedDisplay

Description

HUD game pause display element.
-- Displays a customizable message when the game is paused.
--@category GUI

new

Create a new GamePausedDisplay.

new(string hudAtlasPath)

setPauseText

Set a custom text to display.

setPauseText()

onMenuVisibilityChange

Handle menu visibility state change.

onMenuVisibilityChange()

setScale

Set uniform UI scale.

setScale()

storeScaledValues

Store scaled positioning, size and offset values.

storeScaledValues()

createBackground

Get this element's base background position.

createBackground()

createComponents

Create required display components.

createComponents()

Gui

Description

Graphical User Interface controller.
-- Builds UI from configurations, provides dialog display and propagates UI input.
--@category GUI

loadProfiles

Load UI profile data from XML.

loadProfiles(xmlFilename UI)

loadGui

Load a UI screen view's elements from an XML definition.

loadGui(xmlFilename View, name Screen, controller FrameElement, isFrame [optional,)

loadGuiRec

Recursively load and build a UI configuration.

loadGuiRec(xmlFile Opened, xmlNodePath Current, parentGuiElement Current, target Target)

resolveFrameReference

Tries resolving a frame reference.
If no frame has been loaded with the name given by the reference, then the reference element itself is returned.
Otherwise, the registered frame is cloned and returned.

resolveFrameReference(self Gui, frameRefElement FrameReferenceElement)

getProfile

Get a UI profile by name.

getProfile()

getIsGuiVisible

Determine if any menu or dialog is visible.

getIsGuiVisible()

getIsDialogVisible

Determine if any dialog is visible.

getIsDialogVisible()

getActionEventId

Get a menu action event ID by its name.
Modify GUI action events with care, as they are globally defined for an entire session.

getActionEventId()

showGui

Display and return a screen identified by name.

showGui()

showDialog

Display a dialog identified by name.

showDialog()

closeDialogByName

Close a dialog identified by name.

closeDialogByName()

closeDialog

Close a dialog identified by its root GuiElement.
This is always called when a dialog is closed, usually by itself.

closeDialog()

closeAllDialogs

Close all open dialogs.

closeAllDialogs()

registerMenuInput

Register menu input.

registerMenuInput()

mouseEvent

GUI mouse event hook.
This is used primarily for mouse location checks, as button inputs are handled by InputBinding.

mouseEvent()

keyEvent

GUI key event hook.
This is used for GuiElements which need to have direct access to raw key input, such as TextInputElement.

keyEvent()

update

Update the GUI.
Propagates update to all active UI elements.

update()

draw

Draw the GUI.
Propagates draw calls to all active UI elements.

draw()

notifyControls

Notify controls of an action input with a value.

notifyControls(action Action, value Action)

onMenuInput

Event callback for menu input.

onMenuInput()

onReleaseMovement

Event callback for released movement menu input.

onReleaseMovement()

hasElementInputFocus

Determine if a given GuiElement has input focus.

hasElementInputFocus()

getScreenInstanceByClass

Get a screen controller instance by class for special cases.

getScreenInstanceByClass(table screenClass)

changeScreen

Change the currently displayed screen.

changeScreen(table source, table screenClass, table returnScreenClass)

makeChangeScreenClosure

Make a change screen callback function which encloses the Gui self reference.
This avoids passing the reference around as a parameter or global reference.

makeChangeScreenClosure()

toggleCustomInputContext

Toggle a custom menu input context for one of the managed frames or screens.

toggleCustomInputContext()

makeToggleCustomInputContextClosure

Make a toggle custom input context function which encloses the Gui self reference.

makeToggleCustomInputContextClosure()

makePlaySampleClosure

Make a play sample function which encloses the Gui self reference.

makePlaySampleClosure()

assignPlaySampleCallback

Assign the play sample closure to a GUI element which has the PlaySampleMixin included.

assignPlaySampleCallback(table guiElement)

enterMenuContext

Enter a new menu input context.
Menu views which require special input should provide a context name to not collide with the base menu input scheme.

enterMenuContext(string contextName)

leaveMenuContext

Leave a menu input context.
This wraps the input context setting to check if the menu is actually active and the context should be reverted to
the state before entering the menu (or a custom menu input context within the menu).

leaveMenuContext()

addFrame

Add the instance of a specific reusable GUI frame.

addFrame()

addScreen

Add the instance of a specific GUI screen.

addScreen()

setCurrentMission

Set the current mission reference for GUI screens.

setCurrentMission()

setEconomyManager

Set the current economy manager for GUI screens.
The manager is initialized during mission loading.

setEconomyManager()

loadMapData

Let the GUI (and its components) process map data when it's loaded.

loadMapData(int mapXmlFile)

setClient

Set the network client reference for GUI screens.

setClient()

setIsMultiplayer

Set multiplayer state on screens which need to know about it.

setIsMultiplayer(bool isMultiplayer)

initGuiLibrary

Source in UI modules.

initGuiLibrary(baseDir Base)

GuiElement

Description

GUI Element base class.
All elements displayed in the game UI must be instances or descendants of this class.
-- All XML configuration properties as declared below (and in subclasses) are mirrored in guiProfiles.xml as key-value
pairs in the form of &ltValue name="property_name" value="value" /&gt. Profiles are able to inherit from other
profiles, so take care to check their hierarchy if any of your settings do not seem to have any effect. Directly set
properties in the XML configuration will always override profile values, however.
-- Layer properties, prefixed with "[layer]", interact with an overlay system and provide display images. Usable
layers, whose names are substituted for the prefix, are primarily "image" and "icon". UI elements define layer names
on their own and read them from these generated properties. Whenever an element requires a layer, it is described
in its documentation such as this one. Example for an icon layer focus color property:
iconFocusedColor="0.9 0.1 0.5 1.0".
-- A note regarding callbacks: All callbacks are called on an element's target first. When GUI elements are created from
configuration, their top-level view (e.g. MainScreen) is the callback target, i.e. MainScreen:callbackName() is
executed. Unless an element's target has been set to another value explicitly via code, this will always be the case.
--@category GUI
--@xmlConfig GuiElement#id string [optional] Element ID. Must be unique per GUI screen. If set on an element, will expose it as an indexable field on the view class (e.g. id="buttonOk" -> MainScreen.buttonOk). Use this feature sparingly, as it creates implicit coupling which leads to tedious debugging.

new

Create a new GuiElement.

new(target Target)

loadFromXML

Load element data from an XML definition file.

loadFromXML(xmlFile Definition, key XML)

loadProfile

Load profile data for this element.

loadProfile(profile Loaded, applyProfile If)

applyProfile

Apply a GUI profile with a given name to this element.

applyProfile(profileName Name, bool force)

deleteFrame

Delete any created frame overlays.

deleteFrame()

delete

Delete this GuiElement.
Also deletes all child elements and removes itself from its parent and focus.

delete()

clone

Create a deep copy clone of this GuiElement.

clone(parent Target, includeId [optional,, suppressOnCreate [optional,)

copyAttributes

Copy all attributes from a source GuiElement to this GuiElement.

copyAttributes()

onGuiSetupFinished

Called on a screen view's root GuiElement when all elements in a screen view have been created.
The event is propagated to all children, depth-first.

onGuiSetupFinished()

createFrame

Create frame overlays if this element has a frame.

createFrame()

toggleFrameSide

Toggle a frame side's visibility identified by index.
If this element has no frame this will have no effect.

toggleFrameSide(int sideIndex)

updateFramePosition

Update the frame overlay positions if necessary.

updateFramePosition()

cutFrameBordersHorizontal

Cut horizontal frame borders if a vertical frame side is thicker.

cutFrameBordersHorizontal()

cutFrameBordersVertical

Cut vertical frame borders if a horizontal frame side is thicker.

cutFrameBordersVertical()

mouseEvent

Mouse event hook for mouse movement checks.

mouseEvent()

inputEvent

Handles an input event on a menu input action.
Input is first passed to the current GUI view, then to the focused element, then to the focus manager for navigation.
When a GUI element receives input, it should always propagate the input to its parent element first so they may
override behavior and/or set the event used flag. If properly inherited from GuiElement and descendants, this
behavior is guaranteed.

inputEvent(action Name, value Input, eventUsed If)

keyEvent

Key event hook for raw keyboard input.

keyEvent()

update

Update this GuiElement.

update()

draw

Draw this GuiElement.
If defined, triggers the "onDrawCallback".

draw()

onOpen

Called on the root element of a screen view when it is opened.
This raises the "onOpenCallback" if defined and propagates to all children.

onOpen()

onClose

Called on the root element of a screen view when it is closed.
This raises the "onCloseCallback" if defined and propagates to all children.

onClose()

shouldFocusChange

Determine if this GuiElement should change focus in a given direction.

shouldFocusChange()

canReceiveFocus

Determine if this GuiElement can receive focus.

canReceiveFocus()

onFocusLeave

Called when this element loses focus.
This propagates to all children.

onFocusLeave()

onFocusEnter

Called when this element becomes focused.
This propagates to all children.

onFocusEnter()

onFocusActivate

Called when this element has focus and the focus activation action is triggered.
This propagates to all children.

onFocusActivate()

onHighlight

Called when this element is highlighted.
This propagates to all children.

onHighlight()

onHighlightRemove

Called when this element loses the highlight.
This propagates to all children.

onHighlightRemove()

storeOverlayState

Store the current overlay state while another overrides it (e.g. pressed state)

storeOverlayState()

restoreOverlayState

Restore a previously stored overlay state after an overriding state has expired

restoreOverlayState()

getHandleFocus

Determine if this element can receive focus.

getHandleFocus()

setHandleFocus

Set this elements capability to receive focus.

setHandleFocus()

addElement

Add a child GuiElement to this GuiElement.

addElement()

removeElement

Remove a child GuiElement from this GuiElement.

removeElement()

unlinkElement

Safely remove this GuiElement from its parent, if it has a parent.

unlinkElement()

updateAbsolutePosition

Update this elements absolute screen position.
This needs to be called whenever a position, alignment, origin or size value changes.

updateAbsolutePosition()

reset

Resets the state of this GuiElement and its children.

reset()

isChildOf

Check if this element is the child of another element.
This checks the full parent hierarchy.

isChildOf()

getFocusTarget

Get the actual focus target, in case a child or parent element needs to be targeted instead.

getFocusTarget(incomingDirection (Optional), moveDirection (Optional))

setPosition

Set this element's position.

setPosition()

move

Modify this element's position (i.e. translate position).

move()

setAbsolutePosition

Directly set the absolute screen position of this GuiElement.
Also updates children accordingly.

setAbsolutePosition()

setSize

Set this element's size.

setSize()

setVisible

Set this element's visibility.

setVisible()

getIsVisible

Determine if this element is visible.
This checks both its current alpha value (set by fadeIn() / fadeOut()) as well as the visibility flag. If the parent
is invisible, then so is this element.

getIsVisible()

setDisabled

Set this element's disabled state.
Disabled elements can be displayed differently and do not respond to input actions.

setDisabled(disabled If, doNotUpdateChildren If)

getIsDisabled

Determine if this element is disabled.

getIsDisabled()

getIsSelected

Determine if this element is currently selected.

getIsSelected()

getIsHighlighted

Determine if this element is currently highlighted.

getIsHighlighted()

fadeIn

Fade this element into visibility.

fadeIn()

fadeOut

Fade this element out of visibility.

fadeOut()

setAlpha

Directly set this element's alpha (transparency) value

setAlpha(alpha Transparency)

getIsActive

Determine if this element is active (not disabled and visible).
Does not take alpha value into account.

getIsActive()

setSoundSuppressed

Toggle a flag to suppress UI sounds issued by this element or by the FocusManager when handling this element.
This setting will propagate to children.

setSoundSuppressed()

getSoundSuppressed

Get the sound suppression flag from this element.
If the flag is set to true, no sounds should be played when interacting with this element.

getSoundSuppressed()

findDescendantsRec

Recursively add descendant elements of a root to an accumulator list. If a predicate function is given, it is
evaluated per element and only elements which yield a true value for the function are added to the accumulator.

findDescendantsRec(accumulator List, rootElement Current, predicateFunction [optional])

getDescendants

Get all contained elements of this element in the entire hierarchy.
Descendants are traversed depth-first, meaning that if elements have been properly added, the element order mirrors
the order in the XML configuration (lines). Use this method sparingly, especially on high-level elements.
Optionally, a predicate function can be passed which filters descendant elements. The function must return true for
any desired element and false otherwise.

getDescendants(predicateFunction [optional])

getFirstDescendant

Get the first descendant element of this element which matches a predicate function.
This is a shorthand for getDescendants() which returns just the first element matching the predicate function or nil
if no matching element exists.

getFirstDescendant(predicateFunction A)

getDescendantById

Get a descendant element of this element by its ID.
This is a shorthand for getDescendants() with an ID matching predicate function.

getDescendantById(id Element)

getDescendantByName

Get a descendant element of this element by its name.
This is a shorthand for getDescendants() with an ID matching predicate function.

getDescendantByName(name Element)

updatePositionForOrigin

Get the bit mask value for a position origin string value.

updatePositionForOrigin()

updateScreenAlign

Get the bit mask value for a screen alignment string value.

updateScreenAlign()

getParentBorders

Get the bottom left and top right corners of this element's parent's border rectangle.
If this element has no parent, the full screen's borders are returned (i.e. {0, 0, 1, 1})

getParentBorders()

getBorders

Get this element's border rectangle represented by minimum and maximum points.

getBorders()

getCenter

Get this element's center position.

getCenter()

applyScreenAlignment

Apply screen alignment to this element and its children.
Scales size, position and margin depending on alignment settings.

applyScreenAlignment()

setOverlayState

Set this element's overlay state

setOverlayState(overlayState Overlay)

getOverlayState

Get this element's overlay state.

getOverlayState()

addCallback

Add a callback to this element which was defined in its XML definition.
If this element has a target, the given function name will be called on the target. Otherwise, the function is
assumed to be global.

addCallback(xmlFile XML, key XML, funcName Name)

raiseCallback

Raise a previously added callback by name.

raiseCallback()

extractIndexAndNameFromID

Try to extract a field name and index from an element ID.
IDs in configurations may be indexed on definition (e.g. fillTypes[2]). This function extracts the list name and
index if such a case is found. Otherwise, it will return no index and the original element ID.

extractIndexAndNameFromID(elementId Element)

setId

Try setting this element's ID from its XML definition.

setId()

include

Include a mixin in this element.
See GuiMixin.lua for the details on usage and implementation of mixins.

include(guiMixinType Class)

toString

Get a nice string representation for this GUI element.

toString()

GuiMixin

Description

GuiElement mixin base class.
-- Implements base functionality for GUI element mixins. All other GUI mixins should be descendants of this class.
-- Added methods:
GuiElement:hasIncluded(mixinType) Test if the GuiElement has included a mixin of the given type (class).
--@category GUI

new

Create a new GuiMixin instance.
Subclasses need to provide their class type table for identification.

new(class Class, mixinType Class)