The interface

The JARU IDE window has two parts. At the top, the ribbon: the IDE buttons, on three tabs (Home, Build and Config). Below it, the panels: the project explorer, the editors and the output windows. Panels can be moved, grouped into tabs or taken out into floating windows.

Freshly installed, the IDE puts the explorer on the left, the code editor in the middle and, at the bottom, the Error List and the Output on two tabs. How to change it: The workspace.

The ribbon

Each tab groups its buttons, with the name of the group underneath. A gray button can't be used at that moment: the ones that build, run and debug need an open project, and while the IDE builds, runs or debugs, the ones that don't apply are turned off.

The ribbon has no keys: shortcuts belong to each panel (see Shortcuts).

Home

The Project group opens and closes projects:

Button	What it does
New	Closes the open project and opens the project wizard (Project Wizard), to create one, open another or start from an example.
Open	Opens another project: you pick its .jpr file and the IDE closes the one you had.
Save	Saves whatever is unsaved in every editor (the code, the images, the sprites, the music, the tilemap and the open rooms) and the project's .jpr.
Close	Closes the project and opens the project wizard. If you close the wizard without choosing anything, the IDE is left with no project.

New, Open, Close and closing the IDE first ask about whatever you haven't saved, once for each editor that has something: Yes saves it, No leaves it unsaved and Cancel closes nothing.

The View group opens the panels. Each button opens its panel or, if it is already open, brings it to the front. A panel that isn't part of the window layout opens in a floating window.

Button	Opens	Explained in
Explorer	The project explorer (Explorer)	Projects
Code	The code editor (Code Editor)	Code editor
Images	The image editor (Image Editor)	Image editor
Sprites	The sprite editor (Sprite Manager)	Sprite editor
TileMap	The tilemap editor (Tilemap Editor)	Tilemap editor
Scenes	The scene editor (Scene Editor)	Scene editor
Music	The Music Tracker (Music Editor)	Music Tracker
Output	What the IDE and the serial monitor report (Output)	The Output and the serial monitor
Errors	The errors and warnings in the code (Error List)	The Error List
Git	Version control (Version Control)	Git
I2C Controller	The I2C driver library (I2C Driver Manager)	I2C drivers
Task List	The task list (Tasks Manager)	Code editor

Task List searches the project's code files for comments with TODO, FIXME, BUG, HACK, NOTE, WARNING, OPTIMIZE, REFACTOR or TEMP, written in capitals, and lists them by file. Double-click one to go to that line; Refresh searches again.

Build

The Target group says where the program runs:

• The target button. Target: Windows is the Windows VM. With a board, it shows its chip (Target: ESP32-S3, for example); when you hover over it, it shows the name of the board and its port. Clicking it drops down the menu: Windows x64, the project's boards, with their chip and port, and Manage boards..., which opens ESP32 Tools to add or change them.
• The target is saved with the project. When you choose a board, it also becomes the project's active board, the one ESP32 Tools shows.
• If the board profile of the target no longer exists, the button says Target: (missing): choose another one.
• Line numbers. With the checkbox on, the compiled program carries the line numbers, and an error while it runs says which line it happened on. Off, the program takes less RAM on the board, but errors don't say the line. It is on by default and saved with the project. Debug and the scene editor's Play always build with line numbers.

The Compiler group:

Button	What it does
Compile	Prepares the project's resources (images, sprites, tilemaps and music, in Build/flash) and compiles the main file into Build/flash/<name>.jxr. The main file is the Main File of the explorer or, if there is none, the active tab of the code editor. The Output tells you how it goes.
Run	Runs the program on the target chosen in Target. It builds first if the program isn't built, if you have saved code, images, sprites, tilemaps or music since it was built, or if it wasn't built the way Line numbers asks.
Stop	Stops the program running on Windows, the one from Run or from the scene editor's Play, or the debugging session.

With Run on Windows, the program runs in its own console: that is where what it prints shows up and where readLine reads from. When it ends, the console waits for you to press a key. If the program raises errors, they also show up in the Output.

With Run on a board, the IDE sends it the program, and the Output goes through the three steps: it prepares the files for the board, checks that the board carries the JARU VM (if it doesn't, it offers to write it first with Flash Firmware) and writes the program and its files to it.

Building doesn't save

Compile, Run and Debug compile the files as they are on disk: whatever you haven't saved is left out. Save first with Home › Project › Save or, in the code editor, with Ctrl+S.

The Debug group:

Button	Shortcut	What it does
Debug	F5	Builds the project and starts it in the debugger. It always runs on the Windows VM, even if Target is a board.
Step Over	F10	With the program paused, runs the line without going into the functions it calls.
Step Into		With the program paused, runs the line going into the function it calls.
Continue	F5	With the program paused, carries on to the next breakpoint.
Watch		Opens the Watch window.
GPIO Sim		Opens the GPIO simulator (GPIO Simulator).

The shortcuts work with the cursor in the code editor. How to debug: Debugger; the simulator: GPIO simulator.

Config

Button	What it does
Windows	Opens Windows Tools, the Windows VM settings for this project: the device name (Device Name), the MQTT connection and the size of the program's window (Window Scale, from x1 to x4). They are saved in Config/windows.cfg, inside the project.
ESP32	Opens ESP32 Tools: the project's boards and their board profile, the display, the sound, the SD card, the I2C bus and the network, and the buttons that write the VM firmware and the program to the board.
Settings	Opens Settings: the paths of the compiler and the VMs, the Check for updates on startup checkbox, the AI providers (AI Agents), and Load Layout and Save Layout, which load and save the layout of the panels.
About	Shows the IDE version and the credits (About JARU).
Updates	Checks right away for a newer version of JARU IDE. If there is one, the update notice shows up even if you chose Skip this version or Remind me later before; if not, it tells you that you have the latest one.

Windows and ESP32 are in the Platform group; Settings, About and Updates, in the IDE group. The settings and the update notices are explained in Settings and update notices.

The panels

The explorer

The Explorer panel shows the open project:

• The buttons at the top create files (code, sprites, music, tilemaps, rooms and folders), import images and delete the selection.
• Project: the name of the project.
• Main File: the main file, the one Compile compiles.
• Output: the program (.jxr) left by the last build, the one Run runs.
• Filter: leaves in the tree only the files whose name contains what you type, ignoring case, and the sprites of an actor with that name. The red cross clears it.
• The tree, with the six folders of the project and the size of each file. Double-click a file to open it in its editor, right-click it for its menu, and drag it to move it to another folder.

All of it is explained in detail in Projects.

The editors

The middle of the window belongs to the editors. They open when you double-click a file in the explorer or with their button in Home › View. The code editor, the image editor, the sprite editor, the scene editor and the Music Tracker open each file in a tab; the tilemap editor has a single map open.

Each editor has its own page (see the View table above). The code editor's page is Code editor.

The Output and the serial monitor

The Output is where the IDE tells you what it is doing:

• On startup, the serial ports it finds.
• When building, each step and the result. Errors show up in red, with their file, line and column, and warnings in yellow. If the build fails, the first error is repeated at the end.
• If the build succeeds but the code editor marks errors that the compiler doesn't check, the Output repeats them as a warning: a program that reaches one stops there.
• With Run on Windows, the program's errors, when it ends. What it prints goes to its console, not here.
• With Run on a board, the steps of the upload.
• With the scene editor's Play, also what the game prints.
• While debugging, the line where the program has stopped.
• Whatever comes in through the serial monitor.

Its toolbar:

Control	What it does
Clear Log	Empties the Output.
Open Serial	Opens the serial monitor on the port in Port, at the speed in Speed. While it is open, the button says Close Serial, and closes it.
Port	The serial port. The circular arrows button (Refresh) looks for the ports again and lists them in the Output.
Speed	The speed: from 9600 to 921600 baud. By default, 115200.

The serial monitor shows in the Output what the board sends through the port, such as what your program prints:

• If the Target is a board and you haven't picked another port, Open Serial uses the board's.
• If the port goes away because the board restarts, the monitor opens it again as soon as it comes back.
• While the IDE writes to the board, the monitor steps aside, and comes back when it's done.
• It only receives: it sends nothing to the board.

The Error List

The Error List gathers the errors and warnings that the IDE finds in the project's code, when it opens it and while you type: the same ones the code editor underlines. The compiler's errors don't go here, but to the Output.

• Each row shows the type (the icon), which part of the analysis found it (Stage: Lexer, Parser or Semantic), the message (Message), the file (File), the line (Line) and the column (Column).
• Double-click a row and the code editor opens the file at that line and column.
• Errors, Warnings and Info say how many there are of each type. Clicking one shows or hides that type in the list; hidden, the button says, for example, “0 of 3 Warnings”.
• The (Filter) box leaves only the messages that contain what you type. The cross clears it.
• In the right-click menu, Copy Text copies the selected rows, with their fields separated by tabs.

Watch

Watch (Build › Debug › Watch) shows the value of the variables you ask for while you debug. It is a window that always stays on top of the others. The first time you open it, it appears on the right of the IDE window, halfway down.

• Type the name in the box at the top and press Enter or +. − removes the selected variable, and the circular arrow asks for its value again.
• From the code editor, Add Watch, in the right-click menu, opens Watch and adds whatever you have selected or the word under the cursor.
• Each row shows the name (Name), the value (Value), the type (Type) and where the variable belongs (Context: local or global, for example).
• Instances, sprites and lists can be expanded. If they have many elements, they come in pages, as many per page as Items/page says: 10, 20, 50 or 100.

The values are updated every time the program stops. How to debug: Debugger.

The workspace

Each panel has a header with its name and a cross (Close) that closes it. If it is docked next to another one, it also has a pin (Minimize). On a wide panel, the header goes on the left, vertically; on a tall one, at the top.

• Moving a panel. Drag it by its header or, if it is in tabs, by its tab. While you drag it, the IDE marks where it will go. Drop it next to an edge of another panel and it goes on that side; drop it in the middle and it joins that panel in tabs, like the Error List and the Output. Outside the IDE window, it stays in a floating window, which you can take to another monitor.
• Docking it again. A floating window has a header too: drag it by that header into the IDE window.
• Closing a panel. The cross closes it. It comes back with its ribbon button.
• Shrinking it. The pin collapses it to its header and gives its space to its neighbors. To see it without expanding it, leave the mouse still over the header: it appears on top of the others until you move the mouse away. Click the pin again to put it back in place.
• The header menu. Right-click a header: Locked locks the panels so you don't move them by accident; Undock takes the panel out into a floating window; Header position puts the header at the top, at the bottom or on one side, or wherever its shape calls for (Automatically); Docking options opens the docking settings.

Settings, About and the project wizard aren't panels but ordinary windows. A floating window that doesn't fit on the screen shrinks until it does.

Saving the layout

The IDE starts with the panel layout saved in AppData\Local\JaruIDE\layout.xml. The first time there is none, and it copies the factory one from the installation.

The IDE doesn't save the layout when it closes. To get it the way you have it now next time, press Save Layout, in Config › IDE › Settings. Load Layout goes back to the one you saved.

Back to the factory layout

Close the IDE, delete layout.xml from AppData\Local\JaruIDE and open it again.

Shortcuts

There are no IDE-wide shortcuts: each key works in the panel that has the focus. While you type in a text field, almost every key belongs to the field.

Code editor and debugger

Shortcut	What it does
F5	Debug; with the program paused, Continue.
F10	Step Over.
F9	Sets or removes a breakpoint on the cursor's line.
Ctrl+S	Saves the file of the tab.
Ctrl+F	Opens the find and replace panel.
Ctrl+Space	Opens autocompletion.
Ctrl+J	With text selected, synchronized editing: when you change a name, all its occurrences in the selection change at once.
Esc	Closes the open hint. In synchronized editing, ends it.
Ctrl+Shift+M	Shows or hides the minimap.
Ctrl + click on a name	Goes to where it is defined, also in another file.
Ctrl + wheel	Makes the text bigger or smaller, from 6 to 72 points.
Ctrl+Z and Ctrl+Shift+Z	Undo and redo.
Ctrl+Y	Deletes the line: it doesn't redo.
Ctrl+Shift+Y	Deletes to the end of the line.
Ctrl+N	Inserts a blank line: it doesn't create a file.
Ctrl+T	Deletes to the end of the word.
Ctrl+I and Ctrl+U	Indent and unindent the selected lines.
Alt+Shift+1 and Alt+Shift+0	Fold every block and unfold them.
Ctrl+Shift+B	Jumps to the matching parenthesis, bracket or brace.
Alt+Shift + arrow keys	Select in columns.
↓, ↑, Enter and Esc, in Search symbols...	Open the list of symbols, move through it, jump to the selected one and close it.

F5, F9 and F10 only work with the cursor in the code editor. How to use each thing: Code editor and Debugger.

Scene editor

Shortcut	What it does
1 to 6	Pick Select, Place, Shape, Zone, Pan or Path.
Space, held down	Scrolls the view by dragging.
+, -, F and Ctrl+0	Zoom in, zoom out, fit everything in the view (Fit) and set the zoom to 100 %.
Ctrl+Z and Ctrl+Y	Undo and redo.
Ctrl+S and Ctrl+G	Save and Generate.
Ctrl+C, Ctrl+X, Ctrl+V, Ctrl+D and Ctrl+A	Copy, cut, paste and duplicate the selection, and select every object of the layer.
Del, F2 and Esc	Delete the selection, rename it and empty the selection.
Arrow keys	Move the selection; with Shift, pixel by pixel.
PgUp, PgDn, Home and End	Move the selection in the drawing order.
H and V	Flip horizontally and vertically.

The ones for the Path tool, the mouse and the Problems window are in Scene editor.

Tilemap editor

Shortcut	What it does
Ctrl+Z	Undo.
Ctrl+Y or Ctrl+Shift+Z	Redo.
Ctrl + wheel	Zooms the map, or the palette, in or out.
Right button, over the map	Erases, with any tool.

More in Tilemap editor.

Sprite editor

Shortcut	What it does
Ctrl+Z and Ctrl+Y	Undo and redo.
Ctrl+S	Saves the sprite.
Ctrl+0 and Ctrl+9	Zoom to 100 % (1:1) and the whole sheet in the view (Fit).
+ and -, or Ctrl + wheel	Zoom the sheet in and out.
Space	Plays or stops the animation.
← and →	Go to the previous or the next frame.
Del	Removes the marked frames.

More in Sprite editor.

Image editor

Shortcut	What it does
Ctrl+C, Ctrl+X and Ctrl+V	Copy, cut and paste the selection. When you paste, the editor switches to Select, so you can drag what you pasted into place.
Ctrl+A	Selects the whole image, with Select.
Del	Deletes the selection.
Esc or Enter	Drop the selection.
Arrow keys	Move the selection pixel by pixel.
Ctrl + wheel	Zooms the image in or out towards the mouse.

Del, Esc, Enter and the arrow keys work with the Select tool and something selected. Undo and Redo have no key. More in Image editor.

Music Tracker

Shortcut	What it does
Ctrl+S	Save.
F9	Validate: checks the song.
F5, F6 and F8	Play the song, pause or resume it, and stop it.
Ctrl+F5	Plays the selected rows in a loop.
Ctrl+Z, and Ctrl+Y or Ctrl+Shift+Z	Undo and redo.
Ctrl+L	Turns Loop song on or off.
Ins, Shift+Del and Ctrl+D	Insert a row below, delete the selected rows and duplicate them.
Ctrl+C, Ctrl+X, Ctrl+V and Del	Copy, cut, paste and clear the selected cells.
Shift+↑ and Shift+↓	Pitch + and Pitch -: raise or lower the selection one semitone.
Shift+PgUp and Shift+PgDn	+12 and -12: raise or lower it one octave.
Ctrl+↑ and Ctrl+↓	Change the octave of the computer keyboard.
Ctrl+← and Ctrl+→	Move the on-screen piano.
Alt+1 to Alt+4	Mute a tone channel; with Shift, solo it.
Z S X D C V G B H N J M and Q 2 W 3 E R 5 T 6 Y 7 U	Play notes, like a piano. With REC on, they also write them.
Esc, in the instrument editor	Closes it without saving.

More in Music Tracker.

Other windows

Where	Shortcut	What it does
Watch	Enter, in the box at the top	Adds the variable.
Error List and Tasks Manager	Double-click a row	Goes to that line of the code.
The pin table of the GPIO simulator	Enter and Esc	Accept or discard what you are changing.

Known issues

• The Error List filters don't last. Every time the code editor analyzes the file again, as you type or when you change tabs, the list shows everything again, even though the buttons still say “0 of …” and the filter is still written. To apply them again, type in the (Filter) box.

All the known issues of JARU, together, are in Known issues.