Interface ExtensionContext

public interface ExtensionContext

What an extension may hook into. Each method says which thread its hook runs on. An exception thrown by a hook is printed once, naming the extension, and the hook is switched off; the game goes on.

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static final record	ExtensionContext.DecodedImage	Decoded pixels from an image format of an extension's.
static interface	ExtensionContext.Frame	A drawn frame at stage size; its pixels are read back only when asked for.
static interface	ExtensionContext.ImageDecoder	Turns the bytes of an image file into pixels; runs on loading threads.
static final class	ExtensionContext.InputKey<T>	A slot in the input snapshot: polled on the window thread, copied to the game thread with each batch of ticks, so no locking is needed.
static interface	ExtensionContext.InputSnapshot	The window thread's side of the input snapshot, filled by onInputPoll(Consumer).
static final record	ExtensionContext.KeyEvent	A key went down or up (auto-repeat never arrives).
static interface	ExtensionContext.LayerDrawer	Draws into a layer of a stage.
static final record	ExtensionContext.LearnerError	An exception from learner code, with the learner's frame (null if there is none).
static final record	ExtensionContext.MouseEvent	Something the mouse did, in stage coordinates.

Method Summary

Modifier and Type	Method	Description
void	addLayerDrawer(Layer layer, ExtensionContext.LayerDrawer drawer)	Draws into a layer every frame, after the layer's canvas and before its sprites: map tiles, drawings.
void	addOverlayDrawer(ExtensionContext.LayerDrawer drawer)	Draws above everything (UI, texts and monitors included) in stage coordinates; captures leave it out (Studio's watch pins).
void	afterFrame(BiConsumer<Stage, ExtensionContext.Frame> hook)	After a frame was drawn, on the window thread.
void	beforeTick(Consumer<Stage> hook)	Every tick, after the tick's input and before timers and run().
<T> void	dispatch(Stage stage, Class<T> listener, Consumer<? super T> call)	Calls a listener interface on the stage and every sprite of it that implements it, at the point of the tick where key events arrive.
long	getTickCount()
<T> T	input(ExtensionContext.InputKey<T> key)	This batch's copy of a slot of the input snapshot.
boolean	isLoading()
void	onExit(Runnable hook)	At the end of the program, after whenExits().
void	onInputPoll(Consumer<ExtensionContext.InputSnapshot> hook)	Once per batch of ticks, on the window thread (the one that started GLFW): poll devices into the snapshot.
void	onKey(Consumer<ExtensionContext.KeyEvent> hook)	Every key press and release, before learner code sees it; observe only.
void	onLearnerError(Consumer<ExtensionContext.LearnerError> hook)	A learner exception stopped the game.
void	onMouse(Consumer<ExtensionContext.MouseEvent> hook)	Every mouse event, before learner code sees it; observe only.
void	onStageCreated(Consumer<Stage> hook)	A stage was made (on the thread that made it, usually the game thread or main).
void	onStageDisposed(Consumer<Stage> hook)	A stage stopped being shown.
void	registerImageFormat(String suffix, ExtensionContext.ImageDecoder decoder)	Images whose name ends in suffix (e.g.
void	runOnGameThread(Runnable task)	Runs a task at the start of the next tick, before input.

Method Details

onStageCreated

void onStageCreated(Consumer<Stage> hook)

A stage was made (on the thread that made it, usually the game thread or main).

onStageDisposed

void onStageDisposed(Consumer<Stage> hook)

A stage stopped being shown. Game thread.

beforeTick

void beforeTick(Consumer<Stage> hook)

Every tick, after the tick's input and before timers and run(). Game thread.

onKey

void onKey(Consumer<ExtensionContext.KeyEvent> hook)

Every key press and release, before learner code sees it; observe only. Game thread.

onMouse

void onMouse(Consumer<ExtensionContext.MouseEvent> hook)

Every mouse event, before learner code sees it; observe only. Game thread.

onExit

void onExit(Runnable hook)

At the end of the program, after whenExits(). Game thread.

onLearnerError

void onLearnerError(Consumer<ExtensionContext.LearnerError> hook)

A learner exception stopped the game. Game thread.

addLayerDrawer

void addLayerDrawer(Layer layer,
 ExtensionContext.LayerDrawer drawer)

Draws into a layer every frame, after the layer's canvas and before its sprites: map tiles, drawings. Game thread, when the draw list is made.

addOverlayDrawer

void addOverlayDrawer(ExtensionContext.LayerDrawer drawer)

Draws above everything (UI, texts and monitors included) in stage coordinates; captures leave it out (Studio's watch pins). Game thread.

dispatch

<T> void dispatch(Stage stage,
 Class<T> listener,
 Consumer<? super T> call)

Calls a listener interface on the stage and every sprite of it that implements it, at the point of the tick where key events arrive. Learner exceptions thrown there stop the game like any learner exception. Game thread.

Type Parameters:

T - the listener interface

input

<T> T input(ExtensionContext.InputKey<T> key)

This batch's copy of a slot of the input snapshot. Game thread.

getTickCount

long getTickCount()

Returns:

ticks run so far

isLoading

boolean isLoading()

Returns:

whether the loading screen is up

onInputPoll

void onInputPoll(Consumer<ExtensionContext.InputSnapshot> hook)

Once per batch of ticks, on the window thread (the one that started GLFW): poll devices into the snapshot. GLFW polling functions only; setting GLFW callbacks is not allowed.

afterFrame

void afterFrame(BiConsumer<Stage, ExtensionContext.Frame> hook)

After a frame was drawn, on the window thread.

runOnGameThread

void runOnGameThread(Runnable task)

Runs a task at the start of the next tick, before input.

registerImageFormat

void registerImageFormat(String suffix,
 ExtensionContext.ImageDecoder decoder)

Images whose name ends in suffix (e.g. ".ase") are decoded by decoder.