AGR Coding Guide

AGR (the Aussom Graphical REPL) runs your Aussom code and gives it a graphics area to draw into. Most of what you write in AGR is plain Aussom, and every standard library works the same as it does from the command line. On top of that, AGR adds a small API that exists only while your code runs inside AGR.

This guide covers that AGR-specific API: the two visual surfaces you can reach from your code, and how to get a handle to each one.

The graphics area

The large panel on the left of the AGR window is the graphics area. It is a stack of layers. Two of those layers are yours to draw into from code:

The draw pane - a plain surface where you can lay out JavaFX controls (buttons, labels, charts) for quick testing. You reach it through the agr object.
The FXGL window - a full FXGL game surface for entities, physics, and game views. You reach it through the fxgl object.

The other layers (an app control layer on top, and a reserved notebook layer) are managed by AGR itself and are not part of this API.

The `agr` object

The agr object is your handle to the AGR application from inside your code. It is available only in AGR. A script run from the command line has no agr object, because there is no AGR window behind it.

AGR includes the agr and fx libraries for you at the start of every workspace, so you can call agr.getPane() and use JavaFX controls without an include line for either. (Outside AGR the agr object does not exist, because its include path is registered only on AGR's own interpreter.) You still include the specific control classes you use, such as fx.Button, since those are separate from the base fx library.

Getting the draw pane

agr.getPane() returns the draw pane as a JavaFX Pane wrapper. You add controls to it exactly as you would with any fx pane:

include fx.Button;
include fx.Label;
include fx.VBox;

// Get the AGR draw pane.
p = agr.getPane();

// Build the controls. The button logs a message when it is clicked,
// using a closure as its click handler.
lbl = new Label("Hello from the draw pane");
btn = new Button("Click me");
btn.onClick(::onClickHandler(event) {
    c.info("clicked");
});

// Wrap the controls in a VBox so they lay out top to bottom instead of
// overlapping, then add the VBox to the draw pane.
box = new VBox();
box.setSpacing(8);
box.add([lbl, btn]);
p.add([box]);

The draw pane is a plain JavaFX Pane: it does not arrange its children, so adding several controls directly would stack them at the same spot. Put them in a layout container such as a VBox (as above) and add that container to the pane.

The click handler above is a closure: ::onClickHandler(event) { ... } defines an inline handler named onClickHandler that takes the JavaFX event and runs when the button is clicked. A closure can read variables from the surrounding code, so the handler can use anything in scope.

The value agr.getPane() returns is a live handle to the pane AGR already built for your workspace, so anything you add appears in the graphics area right away. You do not create the pane yourself and you do not add it to a window; AGR owns it and has already placed it in the layer stack.

Showing, hiding, and clearing the draw pane

The draw pane's visibility is controlled from the graphics area itself, using the layer selector in the top-right corner:

Selecting the draw pane in the layer selector shows it. While it is shown, it sits in front of the FXGL window.
Deselecting it hides it again and lets the FXGL window show through.
With the draw pane selected, a Clear action appears that empties the pane of everything you have added.

Whether the draw pane is shown or hidden is remembered per workspace, so a folder reopens the way you left it.

The FXGL window

AGR builds an FXGL game window for you automatically, so you do not launch it yourself. You reach the running game through the standard fxgl object, which AGR also includes for you at start-up.

The usual entry point is the game scene. Add a control to its UI layer with addUINode:

include fx.Button;

// Reach the running game's scene.
gs = fxgl.getGameScene();

// Add a heads-up control on top of the game view.
btn = new Button("Pause");
gs.addUINode(btn);

fxgl.getGameScene() returns the GameScene for the game AGR is already running. From there you have the full FXGL API: addUINode and addUINodes for HUD controls, addGameView for game-world views, and the game world, input, timer, and event bus through the other fxgl accessors. See the FXGL documentation for the complete surface.

Because AGR starts the game for you, AGR also leaves the game handle and its embedded pane in scope as game and pane, so short experiments can use those directly. For anything beyond a quick test, prefer fxgl.getGameScene(), which always points at the running game.

Draw pane or FXGL window - which to use

Use the draw pane when you want to try out JavaFX controls and layouts: forms, charts, buttons, and other standard UI nodes.
Use the FXGL window when you want entities, physics, animation loops, or anything built on the FXGL game engine.

Both live in the same graphics area, one in front of the other, and the layer selector decides which one you see.