Companion Mod

The SimSweep Companion Mod is a Sims 4 script mod that connects your game to SimSweep in real time. When it's running, SimSweep knows what mode you're in, what's on your lot, what your sims are wearing, and when something goes wrong. All of it shows up on your dashboard the moment it happens.

The Companion Mod is built on SYVR Core, a shared Python framework that provides the zone lifecycle management, game hooks, and detection systems it depends on. Both .ts4script files go in your Mods folder.

---

What It Does

• Real-time game mode detection — Live, CAS, Build/Buy, Traveling, Main Menu
• Health monitoring — Exception count, conflict count, sim debt, sim resets, object resets, CC health tracking
• Performance monitoring — Object count, sim count, simulator debt, and performance threshold warnings
• Real-time exception tracking — Script mod crashes flow to SimSweep as they happen, attributed to the specific mod that caused them
• CAS outfit tracking — Shows every outfit slot your sim is wearing, with CC filenames and outfit diffs on exit
• Automated broken CC detection — Detects broken CAS parts and prototype fallback objects at runtime
• Runtime conflict detection — Catches tuning registration collisions the moment they happen, with winner/loser attribution
• Cascade analysis — Maps tuning dependency graphs to show how far a conflict's damage spreads
• CC health tracking — Correlates resets, route failures, and exceptions to specific objects, auto-highlights at 3+ incidents
• Build mode tracking — Real-time object count as you place and remove items
• Session tracking — Records play duration, household, lot, exceptions by mod, and CC IDs seen during each session. Sessions save to a local database automatically.
• CC usage journal — Tracks which CC parts you wear and for how long, CAS try-on vs. keep behavior, and lot object presence across sessions
• Desktop-to-game commands — SimSweep can highlight/unhighlight objects in-game, query outfits, and show in-game notifications. No UI for these yet — the pipeline is ready for future CC browser integration.

---

Installation

The Companion Mod requires two .ts4script files in your Mods folder:

1. Download SYVR_Core.ts4script and SYVR_Companion.ts4script (available from the app or simsweep.com)
2. Drop both into your Sims 4 Mods folder
3. Make sure script mods are enabled in your game settings (Game Options > Other > Enable Custom Content and Mods, and check "Script Mods Allowed")
4. Launch The Sims 4

SimSweep auto-detects the Companion Mod when it's present. The hero banner on the Home page shows your connection status, and you can click "Open Cockpit" to navigate to the full Game Link view.

---

How the Connection Works

SimSweep runs a TCP server on localhost:27220. When the Companion Mod starts (on game launch), it connects as a client and streams game state over the socket as newline-delimited JSON messages.

If the connection drops (happens briefly during zone travel, CAS zone reloads, or if SimSweep restarts), the mod auto-reconnects. SimSweep preserves the dashboard state through brief disconnects so nothing vanishes.

The key messages:

• Handshake — Companion version and capabilities, sent on game startup before zone load
• Heartbeat — Periodic keep-alive
• Game mode changes — When you switch between Live, CAS, Build, etc.
• Health snapshots — Exception counts, conflicts, sim debt
• Exception caught — Individual script mod crashes as they happen, attributed to the suspect module
• CAS outfit snapshot — Full outfit data when entering CAS
• CAS outfit changed — Before/after diff with added/removed parts when exiting CAS
• Performance update — Object count, sim count, simulator debt every 5 seconds
• Performance warning — When performance thresholds are crossed
• Sim/object resets — Individual reset events with source attribution
• CC health updates — Per-object incident tracking, auto-highlight status, top offenders on zone exit
• Broken CC report — Broken CAS parts and prototype fallback objects detected at runtime
• Conflict report — Tuning registration collisions with winner/loser and type info
• Cascade stats — Dependency graph size and edge count
• Build session events — Object add/remove events in build mode
• Flagged items — When you flag a CC item in-game

---

Live Dashboard

When connected, the Home page hero banner shows live game stats inline (household name, object count, error count) with a green pulsing dot. Click Open Cockpit to navigate to the full Game Link page with dedicated module panels.

Game Link Page

The Game Link cockpit shows module panels that update in real time. The active module (matching your current game mode) glows with a colored border. Inactive modules collapse to compact pills showing just the module name and a one-line status.

Tier gating: Free users see all six module slots (Health Ring, Performance Bars, Active Profile, Build Counter, Interaction Bar, Zone Waterfall) but the data is blurred with 8px CSS blur. Each slot shows a "Decrypt" badge and a teaser label (e.g. "Live health monitoring", "Performance metrics"). Decrypt+ users see all data unblurred.

Live Mode (Green)

Connection widget showing household name, lot name, companion version, and health traffic light.

CAS Mode (Purple)

Shows what your sim is wearing — every outfit slot listed with the CC filename or "Game default." When you leave CAS, added parts highlight green and removed parts highlight red so you can see what changed at a glance.

Build/Buy Mode (Blue)

Real-time object tracking. Shows current object count and net change as you place and remove items.

Build mode pauses sim time, so no game messages flow during long decorating sessions. The connection stays alive.

Traveling (Yellow)

Shows "Traveling to new lot" while loading. The companion distinguishes between lot travel and exiting to main menu.

Main Menu

Session recap showing play duration, household/lot, exceptions by mod, and conflict/flag counts.

Game Closed

Shows when the game process has ended. Dashboard resets to idle state.

---

Real-Time Exception Pipeline

Script mod crashes flow to SimSweep in real time. When a mod throws an exception during gameplay, the companion catches it and sends it over the socket immediately. The dashboard's Health module shows which specific mods are crashing and how often.

This data also uploads to the community database when your session ends, so every companion user passively contributes crash data. Way more accurate than manual reporting because it's coming from actual game behavior.

---

CC Health Tracker

The CC Health Tracker runs in the background and correlates problems back to specific objects. When a sim resets, an object resets, or a route failure happens, the tracker increments an incident counter on the involved object.

Once an object hits 3 incidents, it gets auto-highlighted red in-game so you can see it. No action required from you — the broken object just starts glowing.

The tracker sends health updates to SimSweep every 10 seconds with per-object incident counts and names. On zone teardown, it sends a final summary with the top 10 offender objects. SimSweep cross-references these with your mod scan index to identify which .package files are responsible.

---

Runtime Broken CC Detection

This happens completely in the background while you play. The companion scans for two types of broken items:

Broken CAS parts — When loading outfit data, the companion tries to access each CAS part. If the game throws a RuntimeError or returns an invalid body type, the part is flagged as broken. The report includes the sim name, body type, outfit category, and error message.

Prototype fallback objects — When an object's tuning is missing or corrupted, the game falls back to a generic placeholder object. The companion scans lot objects for these fallbacks and flags any it finds.

Reports go to SimSweep over the socket immediately. SimSweep matches the broken instance IDs back to your .package files using the scanner index, then uploads them to the community database automatically.

---

Runtime Conflict Detection

The companion hooks into the game's tuning registration system to catch conflicts the moment they happen. When two mods try to register the same resource (same type + instance ID), the game silently drops one of them. The companion catches this and records which mod won and which got dropped.

It also scans for resources that exist in multiple groups on zone load — these are tuning overrides where one mod is replacing another's tuning.

Conflict reports flow to SimSweep over the socket with the type ID, instance ID, manager type, and winner/loser information. SimSweep matches these against the scan index to show you exactly which mods are colliding.

---

Cascade Analysis

When a conflict is detected, cascade analysis figures out how far the damage spreads. It builds a dependency graph of which resources depend on which.

If Resource A conflicts and Resources B, C, and D depend on A, the cascade analysis reports that this conflict affects 3 downstream resources. This helps prioritize which conflicts actually matter — a conflict affecting 50 downstream resources is more urgent than one affecting 2.

---

CC Usage Journal

The companion tracks how you actually use your CC during gameplay. This is pure analytics — no in-game behavior changes.

Outfit polling — Every 5 sim minutes, snapshots each household sim's outfit. Compares to the previous snapshot to detect what parts were equipped and removed, tracking how long each CC part stays equipped.

CAS tracking — When you enter CAS, it snapshots the outfit before editing. When you exit, it snapshots after. Parts that were in the "before" but not the "after" are tracked as "tried but rejected" — you put something on, didn't like it, and took it off.

Lot objects — On zone load, records all object definition IDs on the lot.

The journal writes to disk on zone teardown. SimSweep reads these journals to build aggregate usage statistics over time — things like "Part X was equipped for 2.3 hours total across all playthroughs" or "Part Y was tried but rejected in CAS 5 times."

---

Automated Community Reporting

Every companion user is a passive data contributor. You don't have to do anything. Broken CC reports, conflict data, and exception attribution upload to the community database automatically when your session ends.

Reports are tagged with autoDetected: true in the database. A daily cron job aggregates the reports into community health scores that show up on CC Hub items. The data is more accurate and covers way more mods because it's coming from actual game behavior, not user opinions.

---

Session Persistence

Every session is automatically saved to a local SQLite database with:

• Session duration
• Household and lot name
• Exception counts and per-mod attribution
• Conflict and flag counts
• Companion version

Sessions under 5 seconds are skipped. Session data accumulates locally for diagnostics and community reporting.

---

Known Limitations

In-game CAS (mirrors, dressers, career outfits, mannequins) is fully detected. The dashboard shows "CAS Mode" with the sim name and outfit category, plus full outfit tracking.

New Game CAS ("Create a Sim" from the main menu) is NOT detectable. This screen runs before mod code can hook into it. Detection resumes when you finish CAS and pick a lot.

---

Cheat Commands

The Companion Mod adds these cheat commands to the game console:

Earlier versions used keyboard hotkeys (F10/F11), but since .ts4script files can't use Python's ctypes for key detection, these were converted to cheat commands.