SYVR Core
The shared Python framework for Sims 4 modding that powers the Companion Mod. 18 modules providing zone-aware lifecycle management, game hooks, event listeners, performance monitoring, and persistence.
SYVR Core is a shared Python framework for Sims 4 modding. It's the foundation that the Companion Mod (and any future SYVR mods) is built on. Instead of every mod reimplementing game hooks, event listeners, and zone lifecycle management, SYVR Core provides a clean API for all of it.
Version 2.3.0. 18 modules. Everything is zone-aware with automatic cleanup on teardown.
Why It Exists
The Sims 4's Python modding API is powerful but low-level. Hooking into zone loading, patching interactions, listening for game events, detecting CAS or Build mode, tracking object resets — all of it requires understanding internal game systems, managing registration/unregistration lifecycles, and avoiding memory leaks when zones unload.
SYVR Core handles all of that. Mod authors register callbacks, and SYVR Core deals with the plumbing: installing hooks at the right time, cleaning up on zone teardown, re-registering when a new zone loads.
Installation
SYVR Core ships as a .ts4script file alongside the mods that use it.
- Drop
SYVR_Core.ts4scriptinto your Sims 4 Mods folder - Make sure script mods are enabled (Game Options > Other > Script Mods Allowed)
- Launch the game
SYVR Core loads automatically on game startup and initializes its systems on each zone load. No configuration needed.
Module Overview
| Module | What it does |
|---|---|
| lifecycle | Zone loading states, 8 checkpoint callbacks, spin-up/load/teardown hooks |
| injection | Auto-registers custom interactions into sim affordance lists |
| patching | Override interaction test/run functions |
| events | TestEvent callback registry (InteractionComplete, StatChanged, etc.) |
| buildbuy | Build/Buy mode enter/exit callbacks |
| cas | CAS enter/exit detection with edit mode context (mirror, dresser, career, etc.) |
| reset_detection | Sim/object reset hooks with source attribution, route failure detection |
| performance | 5-second polls for simulator debt, object/sim budget tracking |
| highlighting | Colored glow effects on game objects (red, yellow, green, blue, orange) |
| ui | Toast notifications, screen slams, OK/Cancel dialogs |
| cas_catalog | Query CAS parts, get outfit composition, apply/remove parts without entering CAS |
| appearance | Reversible appearance modifiers, CC try-on, slot randomization |
| object_tracking | Object add/remove/move callbacks |
| alarms | Real-time and sim-time alarms with auto-cleanup on zone teardown |
| game_service | Custom game services with lifecycle callbacks and JSON persistence |
| settings | Per-mod JSON settings with lazy loading and auto-save |
| simdata | Per-sim persistent data store |
| stat_watchers | Statistic value-change and delta watchers |
Zone Lifecycle
Everything in SYVR Core is zone-aware. The game loads a new zone every time you travel, enter CAS, or return from the main menu. SYVR Core hooks into three lifecycle points:
- Spin-up — Zone is starting to load. Objects and sims aren't ready yet.
- Load — Zone has finished loading. Everything is ready.
- Teardown — Zone is being destroyed. Time to clean up.
Most modules auto-register their hooks on zone load and auto-unregister on teardown. You don't have to manage this yourself.
Zone States
The game has 8 intermediate loading states you can hook into:
| State | Value | When it fires |
|---|---|---|
| ZONE_INIT | 0 | Zone object created |
| OBJECTS_LOADED | 1 | Lot objects instantiated |
| CLIENT_CONNECTED | 2 | Player client connected |
| HOUSEHOLDS_AND_SIM_INFOS_LOADED | 3 | Household data loaded |
| ALL_SIMS_SPAWNED | 4 | All sims placed in world |
| HITTING_THEIR_MARKS | 5 | Sims moving to starting positions |
| RUNNING | 6 | Zone fully running |
| SHUTDOWN_STARTED | 7 | Teardown beginning |
Interaction System
Two modules handle interactions:
Injection
Register interaction instance IDs and they get injected into every sim's affordance list on zone load. Late-spawning sims (NPCs, sims returning from work) also receive the injections automatically.
Patching
- patch_test — Replace an interaction's test function. Your function receives the target, context, and kwargs, and returns a TestResult.
- patch_run — Replace an interaction's run function. Your function receives the interaction and timeline.
Both apply on zone load and are idempotent.
Event System
Register callbacks for any TestEvent (InteractionComplete, StatChanged, etc.). Your callback receives the sim info, event type, and resolver. Filter by a specific key for targeted listening. All listeners auto-unregister on zone teardown and re-register on the next zone load.
Game Mode Detection
Build/Buy
Callbacks for entering and exiting Build/Buy mode.
CAS
Callbacks for entering and exiting CAS. On entry, you get the sim info and edit mode — DEFAULT, MANNEQUIN, CAREER, DISGUISE, GENDER, TATTOO, FASHION, PREFERENCES, or SIM_CUSTOMIZATION. Query functions tell you if CAS is active and which sim is being edited.
CAS detection works for in-game CAS (mirrors, dressers, career outfits, mannequins). New Game CAS from the main menu is not detectable — it runs before mod code can hook into it.
Reset & Route Failure Detection
- Sim resets — Fires on error-triggered resets with the sim info, reset reason, source, and cause.
- Object resets — Fires on object resets with the object, reason, source, and cause.
- Route failures — Fires when a sim can't reach their destination with the failure reason and target object.
Only error resets (reason = 2) trigger sim/object callbacks — normal gameplay resets are filtered out.
Performance Monitoring
Delivers metrics every 5 seconds:
| Metric | What it measures |
|---|---|
| Simulator debt | How far behind the simulation is (in minutes) |
| Total objects | Objects on the current lot |
| Sim count | Instanced sims |
| Object budget % | Object count as % of the 900-object limit |
| Sim budget % | Sim count as % of the 20-sim limit |
Snapshot available on demand without waiting for the next poll.
Object Highlighting
Apply colored glow effects to any game object. Five preset colors (red, yellow, green, blue, orange) with configurable pulse speed and thickness. Optional tutorial text near the object. All highlights auto-clear on zone teardown.
The Companion Mod uses this to highlight broken CC objects in-game after 3+ incidents.
UI Toolkit
Show notifications and dialogs without any tuning XML:
- Toast notifications — Default or urgent priority
- Screen slams — Small, medium, large, or extra large announcements
- OK dialog — Simple acknowledgment
- OK/Cancel dialog — With separate callbacks for each button
No XML tuning files required.
CAS Catalog & Appearance
CAS Catalog
Query and manipulate outfits at runtime without entering CAS. Get current outfit parts, list available parts by body type, apply or remove parts, and check part tags.
Appearance Modifiers
Apply reversible appearance changes using a GUID system. Modifiers are tracked by GUID so they can be cleanly reversed. Higher priority values take precedence. Supports HSV color shifting and layer indexing.
Object Tracking
Track object lifecycle events on the lot — additions, removals, and location changes. Auto-registers on zone load, auto-unregisters on teardown.
Alarms
Create timed callbacks that respect zone lifecycle:
- Real-time alarms use wall-clock seconds
- Sim-time alarms use sim minutes
- Cross-zone alarms survive zone changes (not auto-canceled)
- All other alarms auto-cancel on zone teardown
Persistence
Three persistence systems for different needs:
Settings
Per-mod settings backed by JSON. Lazy-loads on first access, auto-saves on every change. Stored in the Mods folder.
SimData
Per-sim persistent data store. Global across saves, keyed by sim ID. Auto-saves on every change.
Game Services
Full lifecycle services with save/load. Services receive zone load/unload, client connect, and sim spawn callbacks. Data persists as JSON in the Mods folder.
Stat Watchers
Monitor sim statistics for value changes or rate-of-change. Watchers fire when a stat's value changes, with the old and new values or the delta. All watchers auto-clean on zone teardown.
Automatic Cleanup
This is the core design principle. Every system that registers hooks, callbacks, alarms, or watchers automatically cleans up on zone teardown:
- Event listeners unregister
- Alarms cancel (unless cross_zone)
- Object highlights clear
- Stat watchers remove
- Object tracking callbacks unregister
This prevents the memory leaks and stale-callback crashes that plague many Sims 4 mods. Register your callbacks on zone load, and SYVR Core handles the rest.