# SimSync in-game panel · Bridge 0.3.0 / Live 0.2.0 beta

The updated Bridge opens native game dialogs after a playable household finishes loading. It appears once per save slot in each game session. Reopen it any time with `simsync.panel` in the cheat console. Dismissing the panel does not start collection or sharing.

## Install or update

1. Close The Sims 4. Extract the desktop 0.12.0 ZIP outside Mods, or extract the separate game-mods ZIP into a temporary folder.
2. Copy **SimSyncBridge.ts4script** and **SimSyncLive.ts4script** together into your actual **The Sims 4/Mods/SimSyncBridge/** folder. Replace older copies and remove duplicates elsewhere in Mods. Do not unzip the `.ts4script` files. Keep them no deeper than one folder inside Mods.
3. Enable Custom Content and Mods and Script Mods Allowed, then restart. Confirm both scripts appear in the mod list.
4. Launch desktop SimSync 0.12.0, choose the matching save, and keep its terminal open. The desktop writes a small status heartbeat beside the installed Bridge every five seconds.
5. Load a playable household. The SimSync overview should appear after the loading screen. If it does not, use **Ctrl + Shift + C**, enter `simsync.bridge_ping`, then `simsync.panel`.

The panel prefers Lot 51 Core's load event when installed. Without Core, it uses the documented game loading-screen callback. Manual `simsync.panel` remains available if a patch changes the callback. **Automatic Live collection** requires the separately installed current [Lot 51 Core](https://lot51.cc/core), then an explicit switch in Live controls. Core is not bundled.

## Inside the panel

- **Connection & diagnostics:** current decimal save slot, desktop detection, matching Hub pairing, saved-report helper state, Live sharing and last delivery message, mod versions, Core detection, last observation and errors.
- **Household & needs:** paged household member selection, raw needs and known bounds, mood, traits, skills, career and current action when the game exposes them. These are observations, not editable controls. Reopen a screen to refresh it.
- **Live sync controls:** start, stop, capture once, and toggle auto collection. Stop also disables auto collection. Desktop Hub sharing is a separate switch.
- **Export tuning labels:** refresh supported tuning names for the current stable slot. The desktop Refresh button rereads labels even when the save bytes have not changed. This does not save the game.
- **Setup & help:** installation, pairing, troubleshooting and desktop Sim chat instructions.
- **Panel settings & privacy:** toggle the welcome panel and inspect what is read or shared. Manual reopening works while welcome is off.

Pairing and enabling uploads happen in the desktop app. The game panel never reads, asks for, or displays your pairing token. “Desktop detected” is a heartbeat, not proof of delivery. A running saved-report helper is labelled separately from a confirmed Live delivery. A heartbeat older than 20 seconds is offline/stale; the wrong selected slot is identified explicitly. Panel data stays fixed while a dialog is open; Refresh overview reads it again.

## Commands

| Command | Purpose |
| --- | --- |
| `simsync.bridge_ping` | Confirms Bridge 0.3.0 and reports its panel hook. |
| `simsync.panel` | Opens the native game panel. |
| `simsync.export` | Exports tuning labels with an immediate command acknowledgement. |
| `simsync.ping` | Confirms Live 0.2.0. |
| `simsync.live_start` / `simsync.live_stop` | Start or stop observations; stop disables auto collection. |
| `simsync.live_once` / `simsync.live_status` | Capture once or inspect timer status. |
| `simsync.auto_on` / `simsync.auto_off` | Enable auto collection with Core, or disable it and stop. |

## Files and removal

The Bridge writes `simsync-labels.json` and `simsync-bridge-status.json`. Panel preferences are in `simsync-panel-settings.json`; auto collection is in `simsync-auto.json`. Live writes its observation and diagnostic JSON. The desktop writes `simsync-desktop-status.json`, containing slot IDs, flags and a bounded status message, never credentials. No game save is modified and no network call runs inside the mod.

To remove, close the game and desktop app, remove the two SimSync script files and their named JSON files from Mods/SimSyncBridge. Keep unrelated mods and saves. Revoke the desktop connection separately in Sims Hub if desired.

## Required real-game test

This release is compiled for Python 3.7 and checked with mocked game APIs and shipped bytecode. It has **not** been run in your installed game. Native dialog layout and current-patch compatibility remain unverified.

1. Confirm both version commands respond and the panel appears after loading a household.
2. Dismiss and reopen it, navigate every section, and verify Cancel returns to gameplay.
3. Confirm household names, needs and decimal slot; compare with desktop.
4. Test desktop closed, open with correct save, and open with a different save. Status must distinguish them.
5. Export labels, press desktop Refresh and verify supported names update.
6. Start, stop and capture Live. With Core installed, enable auto collection, travel and restart; verify it resumes. Turn it off and verify it remains stopped.
7. Turn off the welcome panel, restart and confirm it stays hidden while `simsync.panel` works.
8. Record game version and errors from desktop Live diagnostics. Do not share connection.json or tokens.

## Send a creation to My Gallery with CC

Use Desktop 0.12.0 with Bridge 0.3.0; Live 0.2.0 is unchanged. Allow Gallery ZIP uploads for this connection in Sims Hub → Game sync, then choose an export engine in Desktop. Original-package mode requires Package inspector. TrayTrim compact mode requires Python 3.12+ and the same user folder configured in Tray & CC. Save the creation to the game's My Library. Desktop → In-game Gallery upload → Prepare My Library → Enable uploads.

Open `simsync.gallery`, or choose **Send to Gallery with CC** in `simsync.panel`. Choose one creation or **Send all on this page** (up to 25). Read the review screen and confirm. The desktop builds separate private ZIPs containing original Tray files and matched/explicitly selected CC. Check **Upload results**; requested is not uploaded. Download confirmed ZIPs from My Gallery in Sims Hub.

Original-package mode covers supported household outfit references, with partial CASP/GEOM dependency resolution. The new TrayTrim compact option uses the full 0.4.0 engine for supported household genetics, sliders and lot/room Build-Buy references. For dependencies not covered by your selected engine, including scripts and unreferenced defaults, enter relative Mods paths in Desktop before preparing. Those extras are added to every selected creation. Read each ZIP's dependency report. Required game packs are not included. Creations must already be in My Library; recent unsaved changes are not captured. Refresh the desktop Library index after changes. Limits remain 1 GB per ZIP and 12,000 Tray files; the package scan retains its documented bounds.

Only the desktop uses the paired connection. The game module has no network client or token, writes only SimSync mailbox files, and does not alter saves, Tray or Mods content. Gallery session uploads start disabled after restarting Desktop. Pause/revoke or disable Gallery permission in Hub to stop further server actions. Real in-game verification remains pending; tests use mocked game APIs.


The optional full TrayTrim desktop workspace provides advanced previews, dependency review and export choices. Close its window before requesting an export from the game. See the current [TrayTrim setup guide](https://anubismods.rangerred221.chatgpt.site/downloads/simsync-traytrim-guide.md). The existing Bridge 0.3.0 and Live 0.2.0 binaries are unchanged. The direct button inside EA’s Gallery is still unfinished.

The unchanged Bridge picker supports at most 3,000 creations (a creation contains several Tray files). Libraries above that count use Tray & CC batch export and manual My Gallery import. Desktop checks this before enabling the game menu, so it cannot fail silently on an oversized catalogue.
