BaseSquareCursor

local BaseSquareCursor = require("Starlit/client/BaseSquareCursor")

BaseSquareCursor is a base class for square cursors, such as the Vanilla building cursor. It exists primarily because Vanilla does not have an easy to use base cursor class: every cursor is built on top of the building cursor, manually disabling all of its functionality. This is hard to work with and requires a large amount of boilerplate code.

To activate a cursor, create an instance of the class and set it as the player’s drag:

local cursor = MyCursor.new(player)
getCell():setDrag(player:getPlayerNum(), cursor)

Warning

The following names are reserved for internal Starlit usage in this class: _isStarlitCursor, _selectedThisTick, _isValidCache, _isValidCacheSquare, rotateKey If you create new members with these names, you may run into issues.

class starlit.BaseSquareCursor

Base class for square cursors.

playerObj: IsoPlayer

The player the cursor belongs to.

xJoypad: integer

Current X co-ordinate of the cursor, if it is controlled by a joypad. -1 means uninitialised or not a joypad player.

yJoypad: integer

Current Y co-ordinate of the cursor, if it is controlled by a joypad. -1 means uninitialised or not a joypad player.

zJoypad: integer

Current Z co-ordinate of the cursor, if it is controlled by a joypad. -1 means uninitialised or not a joypad player.

select(self, square: IsoGridSquare, hide?: boolean): nil

Called when the player clicks on a square.

Parameters:

• square (IsoGridSquare) – The selected square.

• hide? (boolean) – Whether to hide the cursor. Defaults to true.

isValid(self, square?: IsoGridSquare): (valid: boolean)

Called when checking if a square is valid. This function caches the result - in most cases you only want to override isValidInternal.

Parameters:

square? (IsoGridSquare) – The square to check.

Returns:

valid (boolean) – Whether the square is valid.

isValidInternal(self, square?: IsoGridSquare): (valid: boolean)

Calculates if a square is valid. Invalid squares cannot be selected.

Parameters:

square? (IsoGridSquare) – The square to check.

Returns:

valid (boolean) – Whether the square is valid.

render(
    self,
    x: integer,
    y: integer,
    z: integer,
    square: IsoGridSquare
): nil

Called every tick to render the cursor.

Parameters:

• x (integer) – The X coordinate of the square the cursor is over.

• y (integer) – The Y coordinate of the square the cursor is over.

• z (integer) – The Z coordinate of the square the cursor is over.

• square (IsoGridSquare) – The square the cursor is over.

rotateKey(self, key: integer): nil

Called when the player hits a key while the cursor is active. Override keyPressed instead if you don’t want your api to have dumb names

keyPressed(self, key: integer)

Called when the player hits a key while the cursor is active.

Parameters:

key (integer) – The key that was pressed.

onJoypadPressButton(
    self,
    joypadIndex: integer,
    joypadData: JoypadData,
    button: integer
): nil

Called when a joypad button is pressed. For most cases it makes more sense to override the onJoypadPress functions instead.

onJoypadDirDown(self, joypadData: JoypadData): nil

Called when down is presssed on the joypad’s directional pad.

onJoypadDirUp(self, joypadData: JoypadData): nil

Called when up is presssed on the joypad’s directional pad.

onJoypadDirRight(self, joypadData: JoypadData): nil

Called when right is presssed on the joypad’s directional pad.

onJoypadDirLeft(self, joypadData: JoypadData): nil

Called when left is presssed on the joypad’s directional pad.

onJoypadPressA(self, joypadData: JoypadData): nil

Called when the joypad A button is pressed.

onJoypadPressB(self, joypadData: JoypadData): nil

Called when the joypad B button is pressed.

onJoypadPressY(self, joypadData: JoypadData): nil

Called when the joypad Y button is pressed.

onJoypadPressLB(self, joypadData: JoypadData)

Called when the joypad left bumper is pressed.

onJoypadPressRB(self, joypadData: JoypadData)

Called when the joypad right bumper is pressed.

getAPrompt(self): (prompt?: string)

Returns the prompt for the joypad A button.

Returns:

prompt? (string) – Text to display as a prompt for the A button, or nil to display nothing.

getBPrompt(self): (prompt?: string)

Returns the prompt for the joypad B button.

Returns:

prompt? (string) – Text to display as a prompt for the B button, or nil to display nothing.

getYPrompt(self): (prompt?: string)

Returns the prompt for the joypad Y button.

Returns:

prompt? (string) – Text to display as a prompt for the Y button, or nil to display nothing.

getLBPrompt(self): (prompt?: string)

Returns the prompt for the joypad left bumper.

Returns:

prompt? (string) – Text to display as a prompt for the left bumper, or nil to display nothing.

getRBPrompt(self): (prompt?: string)

Returns the prompt for the joypad right bumper.

Returns:

prompt? (string) – Text to display as a prompt for the right bumper, or nil to display nothing.

getPlayer(self): IsoPlayer?

Returns the player who owns the cursor. This is the same as reading the playerObj field directly but accounts for the field being forcibly renamed in 42.20 due to game API changes. If your mod doesn’t support a version before 42.20, read the playerObj field instead as it is faster to do so.

staticmethod new(player: IsoPlayer): (cursor: starlit.BaseSquareCursor)

Creates a new BaseSquareCursor. After creation the cursor can be made active using IsoCell.setDrag().

Parameters:

player (IsoPlayer) – The player to create the cursor for.

Returns:

cursor (starlit.BaseSquareCursor) – The cursor.