Chapter 2: Config and debugging

Activerse.properties

Engine settings are loaded by ConfigPuller from Activerse.properties on the classpath (capital A). The file in the v1.4.2 tree looks like this:

logging=false
fps=60
show_debug=true
dynamicLighting=false

Key	Default in repo	What it does
`show_debug`	`true`	Adds a Debug button on the world. If the file is missing, the code default is also true.
`fps`	`60`	Target frames per second for the game loop.
`logging`	`false`	When true, writes a performance line to `logs.log` once per second.
`dynamicLighting`	`false`	Optional lighting pass. `dynamic_lighting` is accepted as an alias.

Those four keys are engine-only. ConfigPuller never reads them from settings.ini. Game-specific keys (typically game.*) can live in settings.ini via IniUtils.

Debug overlay

With show_debug=true, a Debug button sits on the world. Click it to toggle an overlay. The overlay is not a compiler: syntax errors still fail at compile time, and uncaught exceptions still print to the terminal (often as ACEHS lines — Chapter 3).

When enabled, the overlay draws:

Current FPS
Tick count since the world started
MPS (memory change per second, megabytes)
Each non-static actor: pixel position and whether it currently collides
Loaded image filenames (duplicates show a count; missing classpath files are marked MIA)
Sounds that are playing
Keys currently down (via KeyboardInfo)

Since v1.4.0, actors with isStatic() true (tiles, scenery) are omitted so the list stays usable. You can also override isTickInert() to skip act() on actors that have no per-tick logic.

An End button is always present; it calls Activerse.shutdownApplication().

Reading the numbers

FPS drops when too many images, sounds, or actors update every tick. Match it against the fps target in properties.

MPS is the change in used RAM over the last second. Negative values usually mean the JVM garbage collector ran. Pair FPS and MPS when you suspect a leak or an allocation spike.

Actors confirm an object actually entered the world and whether collision is firing. Images / sounds confirm files resolved. Keys is mainly for input debugging; if a key never appears here, the listener is not seeing it (focus is often on a Swing button instead of the world).

logs.log

Set logging=true in Activerse.properties. Each new run starts a session header, then one line per second from MemoryTracker:

New Log Session @ yyyy-MM-dd HH:mm:ss
(n) | (HH:mm:ss) | MPS: x MB/s | Heap: x MB | Non-Heap: x MB | GC Time: x ms | FPS: x targeting y | Sys Time (ms) | Interval (ticks)

Logs include heap, non-heap, GC time, and tick interval. They do not include actor collisions, image lists, or sounds. Do not share log files casually; they can include machine timing and memory figures even though Activerse does not currently dump personal data.