sdlext - itb-community/ITB-ModLoader GitHub Wiki

Table of Contents

 

sdlext

sdlext.isConsoleOpen

Returns true if console is currently open. false otherwise.

 

sdlext.isMainMenu

Returns true if the player is currently in the main menu. false otherwise.

 

sdlext.isHangar

Returns true if the player is currently in the hangar. false otherwise.

 

sdlext.isGame

Returns true if the player is currently in a game. false otherwise.

 

sdlext.isHangarUiVisible

Returns true if the hangar ui is visible. false otherwise.

 

sdlext.isEscapeMenuWindowVisible

Returns true if the Escape Menu window is visible. false otherwise.

 

sdlext.isSquadSelectionWindowVisible

Returns true if the Squad Selection window is visible. false otherwise.

 

sdlext.isCustomizeSquadWindowVisible

Returns true if the Customize Squad window is visible. false otherwise.

 

sdlext.isAchievementsWindowVisible

Returns true if the Achievements window is visible. false otherwise.

 

sdlext.isPilotSelectionWindowVisible

Returns true if the Pilot Selection window is visible. false otherwise.

 

sdlext.isOptionsWindowVisible

Returns true if the Options window is visible. false otherwise.

 

sdlext.isLanguageSelectionWindowVisible

Returns true if the Language Selection window is visible. false otherwise.

 

sdlext.isHotkeyConfigurationWindowVisible

Returns true if the Hotkey Configuration window is visible. false otherwise.

 

sdlext.isProfileSelectionWindowVisible

Returns true if the Profile Selection window is visible. false otherwise.

 

sdlext.isCreateProfileConfirmationWindowVisible

Returns true if the Create Profile Confirmation window is visible. false otherwise.

 

sdlext.isDeleteProfileConfirmationWindowVisible

Returns true if the Delete Profile Confirmation window is visible. false otherwise.

 

sdlext.isStatisticsWindowVisible

Returns true if the Statistics window is visible. false otherwise.

 

sdlext.isNewGameWindowVisible

Returns true if the New Game window is visible. false otherwise.

 

sdlext.isAbandonTimelineWindowVisible

Returns true if the Abandon Timeline window is visible. false otherwise.

 

sdlext.getUiRoot

Returns the root UI element.

 

sdlext.showDialog

Argument name Type Description
initFn function An initialization function used to create the dialog's UI

initFn:

Argument name Type Description
ui table The UI object the dialog should be added to.
quit function Argumentless function that be invoked to programmatically dismiss the dialog.

Puts a dark overlay on the screen which intercepts key and mouse events and prevents them from reaching the game (exception: for some reason the console receives partial input). The game continues running in the background. Clicking on the dark overlay or pressing Escape will dismiss the dialog.

This function can be used to stack multiple dialogs on top of each other. Only the most recently created dialog is active. Quitting the dialog makes the previous dialog active.

The ui object defines a onDialogExit callback, which can be overridden to run some custom code once the dialog is dismissed.

Example:

sdlext.showDialog(function(ui, quit)
	local clicked = 0

	ui.onDialogExit = function(self)
		LOG("The button has been left-clicked " .. clicked .. " times.")
	end

	local btn = Ui()
		:widthpx(200):heightpx(30)
		:pos(0.25, 0.3)
		:decorate({ DecoButton(), DecoCaption() })
		:caption("Click me!")
		:addTo(ui)

	btn.onclicked = function(self, button)
		if button == 1 then -- left click only
			clicked = clicked + 1

			if clicked >= 10 then
				quit()
			end
		end

		return true
	end
end)

 

sdlext.showTextDialog

Argument name Type Description
title string Title of the dialog
text string Text displayed in the dialog
w number Optional width of the dialog. Defaults to 700 if omitted.
h number Optional height of the dialog. Defaults to 400 if omitted.

Shows a simple information dialog on the screen, which prevents interaction with the game until it is dismissed, either by clicking outside of it, or pressing Escape.

The dialog's height is automatically changed depending on length of the message, up to a maximum of 400px, after which the text becomes scrollable.

Example:

sdlext.showTextDialog(
	"Attention",
	"This is a very important message that demands your attention."
)

 

sdlext.showAlertDialog

Argument name Type Description
title string Title of the dialog
text string Text displayed in the dialog
responseFn function Function which receives index of the clicked button as argument. Can be nil.
w number Optional width of the dialog. Defaults to 700 if omitted.
h number Optional height of the dialog. Defaults to 400 if omitted.
buttons string(s) Varargs. Texts for buttons that will be displayed below the dialog text. Must have at least one argument.

Shows a dialog on the screen, which prevents interaction with the game until it is dismissed. The dialog can only be dismissed by clicking one of the buttons.

Button texts typically should be in all uppercase, to match the game's dialogs' style.

When the dialog is dismissed, the responseFn function is called, with the index of the clicked button as its argument.

The dialog's height is automatically changed depending on length of the message, up to a maximum of 400px, after which the text becomes scrollable.

The dialog's width is automatically changed depending on number and width of buttons. Width is not capped, and putting too many buttons will simply cause the dialog to be too wide to be displayed on the screen.

Example:

local buttons = { "OK, I GOT IT", "JEEZ, LET ME GO ALREADY" }
local responseFn = function(buttonIndex)
	LOG("Clicked button:", buttons[buttonIndex])
end

sdlext.showAlertDialog(
	"Attention",
	"This is a very important message that demands your attention, and it will not allow you to dismiss it without acknowledging its presence.",
	responseFn, nil, nil, buttons
)

 

sdlext.showInfoDialog

Argument name Type Description
title string Title of the dialog
text string Text displayed in the dialog
responseFn function Function which receives index of the clicked button as argument. Can be nil.
w number Optional width of the dialog. Defaults to 700 if omitted.
h number Optional height of the dialog. Defaults to 400 if omitted.

Convenience function to display an information dialog.

Shows an undismissable dialog with the specified title and text, and an OK button.

 

sdlext.showConfirmDialog

Argument name Type Description
title string Title of the dialog
text string Text displayed in the dialog
responseFn function Function which receives index of the clicked button as argument. Can be nil.
w number Optional width of the dialog. Defaults to 700 if omitted.
h number Optional height of the dialog. Defaults to 400 if omitted.

Convenience function to display a confirmation dialog.

Shows an undismissable dialog with the specified title and text, and YES and NO buttons.

 

sdlext.isShiftDown

Returns true if either left or right Shift modifier button is being held down.

 

sdlext.isAltDown

Returns true if either left or right Alt modifier button is being held down.

 

sdlext.isCtrlDown

Returns true if either left or right Control modifier button is being held down.

 

sdlext.getSurface

Argument name Type Description
tbl table Table describing the surface to fetch

Provides caching functionality for SDL surfaces. This way each requested surface is only created once, and then reused, which makes the game more performant.

Fields of tbl argument:

Argument name Type Description
path string Path to the image in resource.dat. Required.
transformations table Table of transformations to apply to the surface. See below. Optional.

 

  • transformations: a list of transformations to apply to the surface. Transformations are applied in the order listed, and can repeat.
Argument name Type Description
scale number Scale of image. Optional.
colormap table Table describing the surface color map. See below. Optional.
grayscale boolean If true, the image will be turned to grayscale. Optional.
multiply color Color tint of the image. Optional.
outline table Table describing the surface outline. See below. Optional.

 

  • outline:
Argument name Type Description
border number Outline thickness. Default: 1
color sdl.rgb Outline color. Default: whtie

 

  • colormap: an array of color substitutions, with the following pattern:

{ sdl.rgb(), sdl.rgb(), ... etc. }

Where color at index 1 is substituted for color at index 2; 3 for 4, and so on.

Example:

-- Creates a surface of the Punch Mech sprite at 2x the scale,
-- with a white border 2px wide, and with part of its coloration
-- replaced with pure green, then tinted red.
local surface = sdlext.getSurface({
	path = "img/units/player/mech_punch.png",
	transformations = {
		{ scale = 2 },
		{ outline = { border = 2 } },
		{ colormap = {
			{ sdl.rgb(136, 126, 68), sdl.rgb(0, 255, 0) }
		} },
		{ multiply = sdl.rgba(255, 192, 192, 255) }
	}
})

-- Creates a semi-transparent surface of the Punch Mech sprite.
-- For simple surfaces, the old way of passing arguments is also supported.
local transparentSurface = sdlext.getSurface({
	path = "img/units/player/mech_punch.png",
	multiply = sdl.rgba(255, 255, 255, 128)
})