https://github.com/1bardesign/garbage_geiger
An audio memory debugging tool for love2d
https://github.com/1bardesign/garbage_geiger
audio debugging love2d lua lua-library memory memory-management
Last synced: about 1 month ago
JSON representation
An audio memory debugging tool for love2d
- Host: GitHub
- URL: https://github.com/1bardesign/garbage_geiger
- Owner: 1bardesign
- License: mit
- Created: 2020-06-28T11:11:29.000Z (almost 5 years ago)
- Default Branch: master
- Last Pushed: 2020-06-29T03:24:06.000Z (almost 5 years ago)
- Last Synced: 2025-01-27T12:48:21.472Z (3 months ago)
- Topics: audio, debugging, love2d, lua, lua-library, memory, memory-management
- Language: Lua
- Homepage:
- Size: 5.86 KB
- Stars: 4
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: readme.md
- License: license.txt
Awesome Lists containing this project
README
# ☢️ `garbage_geiger`
> A dosimeter for garbage exposure in LÖVE
`garbage_geiger` emits a [geiger(-muller) counter](https://en.wikipedia.org/wiki/Geiger_counter) like noise when there is a lot of memory being allocated or garbage being collected. That's all!
This can give a good indication of potential "gc problem" events in your game. If you get a huge chatter after an attack, you may be allocating too much. If you get a roar right around when your game freezes for a frame or three, its a hint that garbage generation might be an issue.
It is designed for use with [LÖVE](https://love2d.org) 11.x and is intended to be easy to drop into existing projects.
Inspired by [malloc_geiger](https://github.com/laserallan/malloc_geiger).
# Features
- One source, on-demand sound generation
- No garbage generated by the module while it's operating, other than garbage generated internally by love
- Internal RNG state to avoid polluting love.math.random
- Configurable for sensitivity in garbage-heavy or garbage-light environments
# Installation
- Copy [garbage_geiger.lua](./garbage_geiger.lua) and [license.txt](./license.txt) somewhere convenient
- Wherever you put dependencies in your project
- `require` it in your code and construct a new instance
- Optionally configure the instance
- The defaults are fine for starters
- Update it each time around your update loop
- Don't forget to pass `dt`
- Optionally provide some way to deactivate it, for when you next say "hrm, maybe this is a garbage issue..."
- Maybe only have it active when some key is held, or via your console
# Example Usage
```lua
--set up our object
local geiger = require("garbage_geiger"):new()
function love.update(dt)
--audio is generated and played
--(can be done anywhere else with access to the time since last frame)
geiger:update(dt)
-- ... (rest of your game logic)
end
```
# Demo
The provided [main.lua](./main.lua) is a simple demo which allows listening the effect for different garbage generation workloads.
# Limitations
- Generates sound buffers at 30hz (configurable in the source), so there's _at least_ that much latency between something happening and it being audible (plus OS mixing, your sound card, any hardware between your machine and the speakers, etc)
- Will not generate sound if there has been garbage generated _and_ cleaned between updates; lua does not expose any way to check this, and even if it did the implication is pretty expensive.
- Does add some CPU load, though generally much less than a millisecond of work per generation.
- The clicks aren't super high fidelity - but they are audible and feel geiger-y!
# Pull Requests
Contributions will be merged "fairly optimistically"; if it adds something meaningful I'm happy to pull it in.
# License
MIT, see [`license.txt`](./license.txt)