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.

player: 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.

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.