StarBreak Plugin Engine (SBPE)
- zoom, faster and more compatible than sbzoom
- arrows pointing towards objectives, trigger indicators
- hide visual noise, with granular configuration
- custom status hud and healthbar
- player list
- 2 modes of centered camera
- borderless windowed mode, but also works with in-game fullscreen
- fps, net lag indicators
- mipmapping (smooth seamless textures when zooming)
- various minor tweaks (disables autokick, autohides mouse cursor, etc)
- most tweaks are configurable and keybindable
- Windows: yes
- Mac: no
- Linux: no
Important: do not run sbpe and sbzoom at the same time!
- set correct game path in
- on windows, start
config.ini if you don't have a config file yet.
config file basics
For booleans, only use values
For colors, use hexadecimal
a is alpha. Use value
0 for "fully transparent";
000000 are "opaque black".
Text sizes can be set to 0 to hide the corresponding element.
You can fully disable any plugin by adding
enabled = no to the corresponding section, or by adding an underscore to the beginning of the file name, or by removing the file from
Most options will take effect whenever the config file is changed, otherwise you'll need to restart the game to see the effect.
Sections of the config:
game: the path to
mipmaps: whether to use mipmapping at all. Recommended to leave enabled, but turn off if you have any problems. Also, see below section "mipmaps and sprite editing".
mipmap_maxlevel: integer, default: 2, recommended sane range: 0 to 4. Determines the maximum mipmap level that will be generated. Increasing this makes sense if you intend to zoom more than 4 times further than your native resolution. Increasing this also increases the amount of sprite sheets and video memory requirements. If you are interested, you can read more about mipmapping on the internet.
yes, the command line window will stay open and show the log in real time. Useful for debugging.
period: polling period in seconds between live reload checks. All plugins and the config can be edited while the game is running, and the changes should in theory be applied in real time. Some settings, like window size, keybinds, mipmaps, require restart.
priority: priority queue for the plugins. The specified plugin's callbacks will be executed first, then all the rest. Can be tweaked to change draw order.
[plugin_zoom] - zoom
fast: whether to use fast method or slow but correct method. Fast method has some minor inaccuracies: some background visual elements can change position when zooming (most prominently, the ai statue in eschaton), and the "outside" of "underground" rooms can be empty when zooming out instead of being filled with tiles. Recommended to enable if you can survive the above.
level: zoom level, represents internal canvas width in pixels.
-1means the native 1:1 scale. Recommended to leave at
-1and set keybind(s) for the level(s) you want. See
[plugin_keybinds]for info about keybinds.
time: transition time, set to 0 for instant. If using slow method, 0 is recommended.
[plugin_misc] - window management and miscellaneous
fixed_window: use borderless windowed mode with predefined location and size.
window_*: window coordinates and size for
centered: center camera on the player. 0 = disabled (default camera), 1 = center when possible, but not go outside of the world border, 2 = center always.
max_bg_value: if background color is brighter than this value, it is reduced to match. Useful when
drawUniform = no(see below).
hide_cursor_after: inactivity time in seconds when mouse cursor is hidden.
draw*: booleans that control different debug modes that are built into the game.
[plugin_fps] - fps and network lag
color: parameters of the fps indicator text.
update: how often the indicator should update, in seconds.
average: the indicator value is an average over this period of time, in seconds. More - less variation, less - faster convergence.
res_color: parameters of the net lag indicator (the "res" value from in-game performance overlay).
res_warning: whenever res value dips below 900, the color of the indicator will be changed to this. If the res value is very unstable, you should consider homing.
[plugin_hud] - custom status hud
y- coordinates of the top-mid point between hp and hpmax indicators.
spacing: this value is added between the lines. With big font sizes, negative values might be preferable.
color_*: font size and color of various elements.
outline: outline size.
bar_height: size of the health bar in pixels. Set to 0 to disable.
bar_y: vertical offset of the health bar from the top of the character.
bar_color: health bar colors.
bar_notches: color of 25HP interval markers on the empty health.
[plugin_map] - (mini)map
visible: is the map visible. Recommended to leave disabled and make a keybind.
small_room: makes the map hide automatically if the fraction of the room that is visible is more in both dimensions than this value. For example, if
small_roomis 2 and half or more of the room is visible, the map is hidden. Only makes sense if you keep the map always visible, otherwise leave at 0.
py: map position relative to window frame, 0 to 1. 0 = top/left, 1 = bottom/right, 0.5 = center.
h: maximum relative part of the screen occupied by the map (1 = all available space). The map is reduced automatically to the lowest scale that makes it fit, preserving aspect ratio.
hide_outside_zones: hide in lobby, home and bosses. Again, only useful if you keep the map always visible.
Rest of the options are element colors. Remember that you can set color to 0 to hide the corresponding element.
[plugin_extra_info] - extra information
trigger_frame: shows rectangles that represent invisible triggers that the game uses to react to players (most prominently in TL and FB, but also pretty much everywhere in doors etc.)
show_hp: display health and armor on top of objects. Yellow numbers are positive, blue - negative. Turns out to be mostly useless, since most bosses don't report their HP to the clients - it just goes negative and doesn't actually represent internal state.
show_uses: show portal player counts and key counts on the depository.
show_room_id: display zone name and floor number in bottom right corner.
arrows: which arrow types are enabled. Available types:
door: next door (additionally, teleporters and mid door in GY)
shop: shop key or shop door
arcade: arcades in GY and TL, waves in UB, miner in FF
hp: health (when not full)
boost: boosts (that are needed)
player: other players
Options that begin with
arrows_ apply to all types. Options that begin with
arrow_TYPE_ apply to the specified type. For example,
arrow_door_color changes color of arrows of type
These sub-options are:
color: the arrow color and the color of the frame that is drawn when the target is visible.
outline: arrow geometry, in pixels.
frame: width of the frame, 0 to hide.
fade: distance in pixels when the frame/arrow start to fade out.
blink: blinking period in seconds, 0 to disable.
[plugin_noise] - hide visual noise
damage_flash_intensity: 0 to 1, scales the intensity of the white flash effect when objects receive damage.
hide_shells: hide other players. Actually bugged at the moment, will replace other players with yellow rectangles.
hide_healthbars: hide various elements of other players.
hide_nameswill also hide factions due to the way it works.
hide_ally_objects: hide all objects created by other players, except for macrons. This includes, but not limited to: bullets, grenades, fire, blasts, rockets.
hide_effects: hide damage effects (flashes/explosion sprites), death animations, particle trails (smoke trails, warp particles).
replace_shake: replace screen shake and flash effects with an indicator in top middle of the screen.
hide_chat: completely hide chat.
[plugin_playerlist] - player list
visible: recommended to keep disabled and add a keybind. Default key is V.
size: font size.
[plugin_keybinds] - bind keys to plugin options
info_time: if > 0, shows debug info about which keybind was triggered in the top left corner.
Rest of the options are keybinds. The format is:
PLUGIN OPTION TYPE VALUE [VALUE...] = KEY
Valid types are:
set: set the option to
hold: set the option to
value1when held, to
toggle: cycle the option to the next value every press
Valid key names are listed here (first column, case sensitive): https://wiki.libsdl.org/SDL_Scancode
One key can be bound to any amount of options, and one option can be changed by any amount of keybinds.
SBPE is compatible with sprite editing. Edit the original sprite sheets (images with long names in
data/texture/). If enabled, mipmaps are re-generated automatically on restart whenever the original sprites are changed.
(Since this uses "last modified" time of the files, if you replace your sheets with a backup, it might not trigger. In this case, delete the corresponding
.m.bpb file to re-generate that particular pack. (For example, to re-generate
performance is way better when compiled and run with pypy (which is the default in prebuilt release). Portable pypy is straight up unpacked into
Make sure all dependencies are in place:
- python 3.5+ or pypy3
- C/C++ compiler that can be found by disttools
- update submodules:
git submodule update --init --recursive
- python modules:
cffi(built-in on pypy),
- SDL: install development libraries for the version used by the game
- Windows: unzip this into
- Linux: install
- Windows: unzip this into
- symquery: download DrMemory release for the appropriate platform and copy symquery to
to compile, run
To make linux binaries distributable, need to set relative RUNPATH:
patchelf --set-rpath $ORIGIN/../pypy/lib build/remote.bin patchelf --set-rpath $ORIGIN/../pypy/lib rectbinpack/_rbp.so
There is live-reloading for plugins. In case of uncaught exceptions, traceback is written to
remote.log. The plugin that caused the error is unloaded until it is edited.
for plugin ideas see
- pypy: https://pypy.org
- cffi: https://cffi.readthedocs.io
- symquery: part of https://github.com/DynamoRIO/drmemory
- mayhem: https://github.com/zeroSteiner/mayhem
- subhook: https://github.com/Zeex/subhook
- plthook: https://github.com/kubo/plthook
- rectbinpack: based on https://github.com/juj/RectangleBinPack
Thanks to Crunchy Games for not stripping symbols from the binary, would probably never make this without them.
ISC on my code; see appropriate readmes or links above for licenses for other projects.
Copyright 2018 atomizer
Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.
THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.