An application with Source Engine integration through VScript and Garry's Mod Lua scripting.
Note
Install the custom SRCBOX cube model into your game before spawning it from SourceBox.
For Portal 2, Left 4 Dead 2 and legacy CS:GO, extract models and materials into portal2, left4dead2 or csgo, respectively. For TF2, CS:S, Alien Swarm and Portal: Revolution, place the files in custom/srcbox inside the game folder.
You can download it here!
- Python Bridge: Spawn props directly from SourceBox into your game
- Multi-game Support: Works across most Source Engine games
- Voidside PULL Mode: Press P in the Voidside scene to hold the current target, silence the music, and show "P U L L". It also triggers automatically while a demo is playing in a Source game
- Picker (Aimbot): Advanced targeting system with priority targeting (Players → Props)
- AWP Quit Trigger: Shoot spawned SRCBOX props with AWP to quit the game (Only for CS:S)
- Auto-Spawner: Automatically spawns cube at random locations on map load
- Auto-load Scripts: Scripts automatically load on every map via
mapspawn.nut
- Automatic Addon Installation: Creates addon structure in
addons/sourcebox/lua/ - Picker (Aimbot): Silent targeting system (NPCs → Players → Props)
- Auto-Spawner: Spawns cube on map load at random locations
- Console Commands:
picker_toggle,picker_next,sourcebox_spawn
Note
Picker aimbot script is little bit buggy on GMod 9.
| Game | VScript | Picker | AWP Quit | Auto-Spawn | Notes |
|---|---|---|---|---|---|
| Team Fortress 2 | ✅ | ✅ | ✅ | ✅ | AWP Quit only for CS:S |
| Counter-Strike: Source | ✅ | ✅ | ✅ | ✅ | |
| Day of Defeat: Source | ✅ | ✅ | ✅ | ✅ | AWP Quit only for CS:S |
| Half-Life 2: Deathmatch | ✅ | ✅ | ✅ | ✅ | AWP Quit only for CS:S |
| Half-Life 1 Source: Deathmatch | ✅ | ✅ | ✅ | ✅ | AWP Quit only for CS:S |
| Game/Mod | VScript | Picker | Auto-Spawn | Notes |
|---|---|---|---|---|
| Entropy Zero 2 | ✅ | ✅ | ✅ | Standalone game |
| Raising the Bar: Redux | ✅ | ✅ | ✅ | Sourcemod |
| Any Mapbase mod | ✅ | ✅ | ✅ | Auto-detected |
Note
Mapbase mods are automatically detected whether they're standalone games or sourcemods. The system checks for a mapbase folder in the game directory.
| Game | VScript Bridge | Auto-Spawn | Picker | Notes |
|---|---|---|---|---|
| Left 4 Dead 2 | ✅ | ✅ | ✅ | Server-side cube physics and Picker for the local survivor host. Commands through left4dead2/ems/ |
| Portal 2 | ✅ | ✅ | Experimental | Single-player console controls. Precaches the custom cube on supported local maps and keeps the game's mapspawn.nut running |
| Portal 2: Community Edition | ✅ | ✅ | ❌ | Strata Source, auto-detected |
| Portal: Revolution | ✅ | ✅ | ❌ | Strata Source, auto-detected. Precaches the custom cube during map startup |
| Counter-Strike: Global Offensive | ✅ | ✅ | Experimental | Legacy CS:GO (csgo.exe). Cube physics on stock maps uses Stripper:Source |
| Alien Swarm | ✅ | ✅ | ❌ | Uses the first marine and precaches the custom cube on supported local maps |
Note
SourceBox sets up these games while they are running. The bridge starts on the next map load. Cube spawning has been verified in all six games listed here.
For stock Portal 2 and Alien Swarm, start SourceBox before loading a fresh local map. SourceBox prepares an entity lump for each supported loose map so the game precaches the custom cube and can spawn it as a physics prop. SourceBox removes its files on exit. Maps with existing external entity overrides need their own compatible cube template.
In Portal: Revolution, SourceBox can also precache the model from the map-start script if the game ignores the entity lump. Start SourceBox before loading the map.
For 32-bit Windows legacy CS:GO, including CrossOver, SourceBox downloads and installs Metamod:Source and Stripper:Source when needed. Start the local game with -insecure for plugin support. If SourceBox installs the add-ons, restart CS:GO once with SourceBox still open. Then load a stock map and click the cube. SourceBox restores your Stripper configuration when it exits.
The standalone map copy is also available with python -m sourcebox.bridges.cube_precache "/path/to/csgo" cs_office. Load it with map cs_office_sourcebox.
Portal 2, CS:GO, Alien Swarm and Strata can't read files from scripts, so SourceBox sends each command as a tiny script (
sourcebox_command.nut) that the game re-runs, and spawn results show in the game console. Install the cube model for the game before trying to spawn it. Games that require a precached cube may skip spawning when the model or map template is missing.
On a local Left 4 Dead 2 campaign, type !picker in game chat to toggle aim lock and !pickernext to cycle visible targets. Picker applies to the host playing as a survivor and prioritizes infected, then teammates, then physics props. A target you choose with !pickernext stays selected while visible. The map must load the updated bridge once. After that you can restart SourceBox on the same map and turn Picker back on in chat.
To try the experimental Picker in stock Portal 2, start SourceBox and load a local single-player map. In the developer console, run sv_cheats 1, then script PickerToggle(). Picker prioritizes visible turrets, then cubes and other physics props. Use script PickerNext() to choose a target and script PickerToggle() again to release aim lock.
The experimental legacy CS:GO Picker uses the same console commands in a local practice match with one human player. It prioritizes visible enemy bots, then teammates, then physics props. In both games, a manual selection stays locked while the target remains visible.
| Version | Lua Bridge | Picker | Auto-Spawn | Notes |
|---|---|---|---|---|
| GMod 9 | ✅ | ✅ | ✅ | Picker little bit buggy |
| GMod 10 | ✅ | ✅ | ✅ | Sourcemod |
| GMod 11 | ✅ | ✅ | ✅ | Sourcemod |
| GMod 12 | ✅ | ✅ | ✅ | Sourcemod |
| GMod 13 | ✅ | ✅ | ✅ | Retail install, 32-bit or 64-bit (gmod_win64.exe) |
- Works with any Source mod without VScript support or Lua support
- Only cube spawning supported
- Brief window freeze during spawn
- Linux not supported
- Download the latest release from Releases
- Extract the ZIP file
- Important: Launch your game before running SourceBox
- Run
SourceBox.exe(Windows) or./SourceBox(Linux)
- Python 3.7 or higher
- pip package manager
- A supported Source Engine game or Garry's Mod installed via Steam
- Clone the repository:
git clone https://github.com/programmer1o1/sourcebox.git
cd sourcebox- Create a virtual environment (Linux):
python -m venv myenv
source myenv/bin/activate- Install dependencies:
pip install -r requirements.txtNote: This installs
pygame-ce(imported aspygame). If you previously installedpygame, uninstall it first to avoid conflicts.
-
Important: Launch your game before running SourceBox
-
Run the application:
python Sourcebox.py- Left Click: Interact with objects
- Cube: Spawn SRCBOX cube in-game
- Sphere: Toggle error scene
- Cone: Enter Voidside tracker mode
- P (Voidside scene): Toggle PULL mode
- ESC: Exit application
- Launch a supported Source game (TF2, CS:S, DOD:S, HL2:DM, HL1S:DM) or any Mapbase mod
- Launch SourceBox
- Scripts automatically install to:
game/scripts/vscripts/python_listener.nutgame/scripts/vscripts/picker.nutgame/scripts/vscripts/auto_spawner.nutgame/scripts/vscripts/vscript_server.nut(Mapbase only)
For Mapbase mods:
- Files are stored in
vscript_io/instead ofscriptdata/ - Uses Mapbase-specific VScript API
- Auto-loads via
vscript_server.nut
Spawning Props:
- Click the cube in SourceBox
- Prop spawns at your crosshair
- Works in single-player or local listen servers
Picker Commands:
script PickerToggle() // toggle aimbot on/off
script PickerNext() // manually cycle to next targetYou can also set binds like these
bind mouse4 "script PickerToggle()"
bind mouse5 "script PickerNext()"
bind kp_plus "script PickerToggle()"
AWP Quit Feature:
- Shoot any spawned SRCBOX cube with AWP
- Game quits immediately
- Only works in CS:S
Manual Script Loading (if auto-load fails):
TF2 branch of Source Engine:
sv_cheats 1
script_execute python_listener
Mapbase:
exec mapbase_default
script_execute vscript_server
- Launch GMod 9 (gmod9), 10 (garrysmod10classic), 11 (garrysmod), 12 (garrysmod12) (sourcemod version), or retail GMod 13 (GarrysMod/garrysmod)
- Launch SourceBox
- Addon automatically installs to:
garrysmod/addons/sourcebox/lua/autorun/sourcebox_init.luagarrysmod/addons/sourcebox/lua/autorun/sourcebox/sv_*.lua
- Restart GMod game to load addon on first install (Optional for GMod 9)
Console Commands:
picker_toggle // toggle aimbot silently
picker_next // cycle to next target
sourcebox_spawn <model> [distance] // spawn any model
Examples:
picker_toggle
sourcebox_spawn props_junk/PopCan01a.mdl 300
sourcebox_spawn props/srcbox/srcbox.mdl
Spawning Props:
- Click the cube in SourceBox
- Prop spawns at crosshair
- Props are fully visible and interactive
Requirements:
- Windows only
- Running Source mod detected automatically
Spawning:
- Click cube in SourceBox
- Console briefly opens, executes commands, closes
- Window may freeze for ~200ms
- Only SRCBOX cube supported
The native macOS build scans CrossOver's configured private and published bottle directories for Steam. It supports the file-based VScript and Garry's Mod Lua bridges, including games launched through Wine/CrossOver command wrappers.
Legacy Windows console injection is not available from the native macOS build. Install Steam and the Source game in a CrossOver bottle, launch the game first, then start SourceBox.
- Unzip
SourceBox-macOS.zipand moveSourceBox-macOS.appto Applications. - Start Steam and the Source game inside CrossOver.
- Open SourceBox. If macOS blocks the first launch, Control-click the app, choose Open, then confirm Open. Alternatively, use Open Anyway in System Settings > Privacy & Security.
The build is currently distributed without Apple notarization, so the first-launch
confirmation is expected. SourceBox writes startup and game-detection details to
~/Library/Logs/SourceBox/sourcebox.log.
"No game configured" error:
- Make sure game is running before launching SourceBox
- Check that game is installed via Steam
- Try restarting Steam
- On macOS, confirm Steam and the game are running in the same CrossOver bottle
- Check
~/Library/Logs/SourceBox/sourcebox.logfor the detected bottle and game
Scripts not loading in Source games:
- Type
sv_cheats 1in console - Manually run:
script_execute python_listener
GMod addon not working:
- Make sure you're using GMod 9, 10, 11, or 12 (sourcemod)
- Restart GMod after first install
- Check
garrysmod/addons/sourcebox/exists - Use
lua_run include("autorun/sourcebox_init.lua")to manually load
AWP quit not working:
- Only works in CS:S
- Must shoot SRCBOX cube specifically
- Requires AWP weapon
# install development dependencies
pip install -r requirements.txt
# test bridges standalone
python source_bridge.py # test source engine bridge
python gmod_bridge.py # test gmod bridge
# run in verbose mode
python Sourcebox.pyWindows:
pip install pyinstaller
pyinstaller --onefile --windowed --name SourceBox ^
--icon=assets/images/sourcebox.png ^
--add-data "assets;assets" ^
--add-data "bridge_scripts;bridge_scripts" ^
--exclude-module pkg_resources ^
--exclude-module setuptools ^
--noupx --clean Sourcebox.pyLinux:
pip install pyinstaller
pyinstaller --onefile --windowed --name SourceBox \
--icon=assets/images/sourcebox.png \
--add-data "assets:assets" \
--add-data "bridge_scripts:bridge_scripts" \
--exclude-module pkg_resources \
--exclude-module setuptools \
--hidden-import=OpenGL.platform.glx \
--hidden-import=OpenGL.arrays.vbo \
--collect-all OpenGL \
--noupx --clean Sourcebox.pymacOS:
pip install pyinstaller
pyinstaller --onedir --windowed --name SourceBox-macOS \
--icon=assets/images/sourcebox.png \
--add-data "assets:assets" \
--add-data "bridge_scripts:bridge_scripts" \
--hidden-import=OpenGL.platform.darwin \
--hidden-import=OpenGL.arrays.vbo \
--collect-all OpenGL \
--noupx --clean Sourcebox.py
xattr -crs dist/SourceBox-macOS.app
codesign --verify --deep --strict dist/SourceBox-macOS.app
ditto -c -k --sequesterRsrc --keepParent \
dist/SourceBox-macOS.app dist/SourceBox-macOS.zipOutput: dist/SourceBox.exe (Windows), dist/SourceBox (Linux), or
dist/SourceBox-macOS.zip (macOS).
For Source Engine:
- Place models in
game/custom/yourmod/models/props/ - Spawn via Python:
bridge.spawn("props/yourmod/model.mdl", 200)For Garry's Mod:
gmod_bridge.spawn_model("props/yourmod/model.mdl", 300)Or in-game console:
sourcebox_spawn props/yourmod/model.mdl 300
- Method: File I/O via
scriptdata/folder - Files:
python_command.txt,python_response.txt - Format: JSON with session ID and command counter
- Rate: Commands checked every 100ms
- What: Everything SourceBox installs into a game (scripts, addon folders, command files) is removed when SourceBox closes, and any game file it replaced, such as Portal 2's
mapspawn.nut, is restored - Killed or crashed: A small background copy of SourceBox waits for it to exit and cleans up even after "End process" in Task Manager; anything still left is cleaned at the next start
- Record:
installed.json(plusbackups/) in SourceBox's log folder - Edited files: A file you changed after SourceBox wrote it is left in place
- In-game: On the newer VScript branches the bridge stops polling as soon as its command file is gone, so closing SourceBox mid-map causes no console spam
- Method: A hidden worker process (SourceBox relaunched with
--demo-scan-worker) checks Source game processes, found by theirsteamappspath pluswineserver, for open.demfiles withpsutilabout once a second - Why a separate process:
psutilholds Python's global lock while listing open files, which would freeze rendering if it ran inside the app - Requirements: No launch options or game-side script
- Verified: macOS with CrossOver (Counter-Strike: Source, Half-Life 2: Deathmatch); Windows and Linux are untested
- Limitation: Recording a demo also triggers PULL mode
- Method: File I/O via
vscript_io/folder (Mapbase-specific) - Files:
python_command.txt,python_response.txt - Format: JSON with session ID and command counter
- Rate: Commands checked every 100ms
- Detection: Automatic via
mapbase/folder presence
- Games: Left 4 Dead 2, Portal 2, CS:GO, Alien Swarm, Strata Source (P2CE, Portal: Revolution)
- Script: one shared
sourcebox_bridge.nut, loaded frommapspawn.nut(mapspawn_addon.nuton L4D2) - L4D2: JSON in
ems/sourcebox_command.txt, results inems/sourcebox_response.txt - Others: JSON wrapped in
scripts/vscripts/sourcebox_command.nut, re-run withDoIncludeScript; results print to the game console - Existing hooks: a game's own
mapspawn.nutis kept assourcebox_original_mapspawn.nutand still runs first - Detection: Strata games are recognised by the script runtime beside the launcher. Older Portal: Revolution builds use
vscript.dlland are also recognised through the Steam library under CrossOver. - Rate: Commands checked every 100ms
- Method: File I/O via
data/folder - Files:
sourcebox_command.txt,sourcebox_response.txt - Format: JSON with session ID and command counter
- Rate: Commands checked every 100ms
- Addon Path:
addons/sourcebox/lua/autorun/
- Method: Windows API message sending
- Process: Freeze window → Open console → Paste command → Execute → Close console → Unfreeze
- Limitation: Windows only, visual freeze, cube only
This project is licensed under the MIT License - see the LICENSE file for details.

