# SimSync Live 0.2.0 beta

Live game → desktop SimSync 0.10.0 → your private Sims Hub / Android app.

This is an experimental read-only companion. Protocol, relay, access checks and mock game API tests are automated. Actual Sims 4 compatibility has not been verified. Test on a backup of your save first. Manual Live controls need no external script library. Optional automatic collection uses the separately installed Lot 51 Core. The updated Bridge adds the native game panel; see IN-GAME-GUIDE.md.

## Install

1. Download and extract the whole desktop SimSync 0.10.0 ZIP outside your Mods folder. Install Node.js 22.13+ if needed. Close older SimSync launchers before using it.
2. Copy **SimSyncLive.ts4script** into **The Sims 4/Mods/SimSyncBridge/**. Use the actual user-data folder, including a relocated Documents folder. Replace the previous Live mod while the game is closed. Keep exactly one copy, at most one folder deep. Do not unzip the `.ts4script` itself. Replace the older `SimSyncBridge.ts4script` with the included 0.2.0 copy to get the native in-game panel and stable-slot label exports.
3. Enable Custom Content and Mods and Script Mods Allowed in the game, then restart it. Confirm **SimSyncLive** appears in the script mod list. Patches can turn these options off again.
4. Run **Start-Windows.cmd** or **Start-macOS.command** from the extracted desktop app. Open the `.save` for the game you are playing. If a launcher cannot run, use `node app.mjs` in that folder.
5. Load the household in the game. Open the cheat console with **Ctrl + Shift + C**, enter `simsync.ping` and look for **SimSync Live 0.2.0 loaded**. Then enter `simsync.live_start` and check the reported decimal slot ID.
6. In desktop **Live game**, review the household, selected Sim and slot. If they match, pair that save using **Connection** and press **Share live with Hub** on the Live screen.
7. On Android open **More → Game sync & Live**. On the site open **Sims Hub → Game sync**. Select the same save collection. The Live panel refreshes about every five seconds while visible. APK 0.2 already loads this updated panel; a new APK is not required.

Live sharing starts off every time the desktop app launches. The normal **Start sync** button controls saved reports separately. Turning either stream off does not turn the other one off.

## Game commands

| Command | Result |
| --- | --- |
| `simsync.ping` | Confirms the command module loaded without needing household data. |
| `simsync.live_start` | Exports once and starts a game-thread timer at roughly 10-second intervals. |
| `simsync.live_stop` | Cancels the timer and publishes a final stopped observation when a household is available. |
| `simsync.live_once` | Exports one observation without starting a timer. |
| `simsync.live_status` | Shows timer state, slot, sequence and the latest error, if any. |

By default, start again after restarting the game. With the current Lot 51 Core installed, `simsync.auto_on` enables persistent auto collection after household load/travel. `simsync.auto_off` or `simsync.live_stop` disables it and stops collection. The panel has the same controls. Loading, travel, pausing or a changed game API may delay or interrupt the timer. If updates stop after traveling, try `simsync.live_start` again. No threads or network calls run inside the game.

## What is read

- Current save slot ID, current zone ID and lot name when exposed.
- Active household name, funds and up to 32 members.
- Selected Sim ID, member names, age/gender/species enum names, mood tuning name.
- Up to 16 motive statistics per Sim, with raw values and only the bounds actually exposed by the game. This includes supported loaded custom motive tuning; it does not identify every modded need.
- Up to 12 traits, 16 skill levels, a career and current/queued action labels per Sim when exposed. Extended context is omitted if needed to stay within the mailbox limit.
- Observation time, session ID, sequence and availability notes.

Missing values remain unavailable. No fake needs, inferred emotions, generated portraits or screen-reading is used. Mood/motive text is internal tuning naming, not translated game display text. Some occult/pet needs may not be exposed. Only the active household is sampled, not every Sim in the save.

## How it stays separate

The mod atomically replaces **simsync-live.json** beside itself. This is a one-observation mailbox, capped at 64 KB, not an accumulating event log. The relay only reads this file in `Mods/SimSyncBridge` or `Mods`; it ignores symbolic links and never touches another mod's queue. A separate **simsync-live-status.json** records mod load, commands and bounded errors, without household details. Both files use atomic temporary writes.

The desktop rejects other save slots, oversized/invalid payloads, old observations and incorrect clock times. It retries network failures with a bounded backoff and does not upload an old offline backlog. HTTPS uploads use your existing save-scoped device connection. Your device secret stays on the computer, never in the local browser UI or mod.

The Hub stores only the newest live observation per connection. Observations older than 90 seconds since receipt or 120 seconds since capture show disconnected. Pause blocks new uploads; revoke deletes the retained live observation. Old observations remain explicitly timestamped until overwritten or revoked. No live changes write into planning records or saved-game reports. No raw saves, Mods, screenshots or voice are uploaded by Live.

## Test on your computer

Record your game version and these results before considering this compatible:

1. Mod appears in the installed script list; `simsync.ping` prints the installed version.
2. Start in a loaded household. Desktop shows the correct household, slot and lot, with no need to save.
3. Select a different household Sim. Verify the Selected badge changes after about 10–20 seconds.
4. Let a supported need change naturally. Verify the raw value changes, or record that the field is unavailable.
5. Enable Hub sharing. Confirm the phone shows the same names, selected Sim and observation time.
6. Travel, pause/unpause, switch households and load a different save. Confirm wrong-slot observations are rejected and your plans do not change. Restart Live if the game timer stops.
7. Stop the mod. Confirm Stopped; close the game and allow two minutes to confirm Disconnected. If the relay is closed before the stopped message uploads, Disconnected is expected instead.
8. Pause the Hub connection. New uploads should be blocked. Resume it, then revoke the test connection and confirm live data disappears.
9. Restart the desktop app. Confirm Live sharing is off. Restart the game. Confirm manual mode requires a new start, or that explicitly enabled Core auto collection resumes.

## Troubleshooting and removal

Silent console or unknown command: open desktop **Live → Live diagnostics**. It shows the expected Mods folder, whether the file is present, duplicates in the supported folders, and the last diagnostic timestamp. File presence alone does not prove the game loaded it. Check Script Mods Allowed, replace the old mod, remove duplicates, restart, and enter `simsync.ping`. If it stays silent, report whether SimSyncLive appears in the game’s script mod list. No data: load a household, then use `simsync.live_once` and check for `simsync-live.json` beside the mod. The desktop must open a save from that same user-data folder. Slot mismatch: choose the actual matching save; do not edit slot IDs to force acceptance. Version 0.2.0 asks the game for its stable slot GUID before falling back to the embedded slot. The desktop uses the standard filename only when the embedded ID is zero or missing, with an explicit warning. Confirm both IDs agree before pairing. Older Hub collections showing slot 0 need their real slot entered when creating a new connection; existing records are not automatically reassigned. Clock warning: correct the computer date/time and restart the game. No periodic updates: use status, restart Live or export once and report the game version and exception class. Do not share pairing codes or connection.json.

To uninstall, stop sharing, revoke the connection if desired, close the game and remove `SimSyncLive.ts4script`, `simsync-live.json`, `simsync-live-status.json` and their `.tmp` files from your Mods folder. Keep your game saves and other mods.

## Technical references

The context collector adapts selected SimAI code; full credits and MIT terms are in OPEN-SOURCE-NOTICES.md and licenses/. Optional Core event integration requires a separate Core install. API usage was checked against creator-maintained public references, not a guarantee for the installed game patch:

- Lot 51's explanation of game-thread real-time alarms: https://modthesims.info/showthread.php?t=651671
- Lot 51's stable save slot lookup: https://github.com/lot51/core-library/blob/main/utils/context.py
- S4CL's household and active-Sim utility API usage: https://github.com/DeviantGameMods/Sims4CommunityLibrary/tree/main/Scripts/sims4communitylib/utils/sims
- Local file communication inspiration: https://simsweep.com/docs/game-link . No SimSweep code, queues, commands or private APIs are used.

Desktop Sim chat is available with a local Ollama model. Voice, screen vision and game-control commands remain future work.
