# SimSync 0.12.0 beta

Your Sims 4 companion, built around the second-screen approach of Anubis Cyberdeck. SimSync runs on your gaming computer and opens its own dashboard in a browser. Your existing Sims Hub remains connected for planning, AI and finished Sim ZIPs.

## In-game Tray + CC ZIP uploads (0.12.0)

1. Close the game and replace Bridge with 0.3.0 from this download. Keep Bridge and Live together in `Mods/SimSyncBridge`. Live remains 0.2.0.
2. In Sims Hub → Game sync, allow **Gallery ZIP uploads** for this paired connection. Permission starts off. This permits new Gallery profiles and their attachments in the paired collection, not private record/download reads.
3. In Desktop, open the matching save, pair it, then run **Package inspector** for original-package mode or configure **Tray & CC** for compact mode. Save each creation to **My Library** in the game using its normal controls.
4. Open **In-game Gallery upload** in Desktop. Optionally list extra `.package` or `.ts4script` files relative to Mods, one per line. Extras apply to EVERY selected creation. Prepare My Library, then enable uploads for this desktop session.
5. In a loaded household, open `simsync.gallery` (Ctrl+Shift+C), or SimSync panel → **Send to Gallery with CC**. Review one creation, or all 25 on the displayed page, then confirm.
6. Keep Desktop open and check **Upload results**. “Requested” is not a receipt. “Uploaded” means the server verified and attached the ZIP. Open **My Gallery** in the connected Hub to download it.

Each separate ZIP contains original `Tray/` files, original matched/selected `Mods/` files in original-package mode, or trimmed CC packages in TrayTrim mode, a dependency report with SHA-256 checksums, and installation notes. Files are copied read-only, never modified or automatically installed. Existing profile edits remain. ZIPs stay private and use checksummed, resumable 8 MiB parts, up to 1 GB per ZIP. Selecting the same unchanged creation resumes an interrupted transfer without duplicate attachments. Re-prepare after changing Library or Mods files. Disable the desktop session before changing saves or pairing.

**Coverage is partial.** Original-package mode follows supported household outfit CASP/GEOM references; lots/rooms in that mode only include manually selected extras. TrayTrim compact mode uses the complete 0.4.0 engine for households, genetics, sliders and supported lot/room Build-Buy dependencies, with pack exclusions when the game installation is indexed. Sliders, presets, script/tuning dependencies, other resource types and required game packs are not guaranteed. Original-package detection uses the Package inspector's existing bounded scan (up to 2,000 packages / 4 GB; 64 MB per package). Check scan warnings. Extra files are also limited to 64 MB each, up to 200 paths. No missing CC is downloaded. No Sims 4 Tray Importer code is embedded.

Local ZIPs and token-free receipts stay in the desktop settings folder's `gallery-exports` directory. Remove old exports there when no longer needed. The mod exchanges only a local catalogue and explicit request; the pairing token stays in Desktop. This is a SimSync native dialog, not an EA Gallery button or automatic save-to-Library action. Automated game API mocks are tested; actual in-game layout, patch compatibility and installation still need a real game test.

## Shared Gallery and household update

The bundled Workshop now includes Gallery planning links, detailed household/Sim dossiers, named traits when resolvable, expanded Tray metadata and individual portraits, and searchable imported reports. See WORKSHOP-GUIDE.md for the 15 improvements and exact import limits. Existing Tray profiles can refresh imported details through an explicit checkbox. Official Gallery search/downloads still happen through EA; SimSync reads your selected Library files.

## Updated in 0.10.0

**Organizer → Creator records & change tracking** adapts MIT-licensed sims4modorganizer metadata and verification. Scan your Mods, edit a file's name, creator URL, manual version and tags under Details, then explicitly accept a reviewed scan as the SHA-256 baseline. Later scans distinguish matching, new, changed and missing paths. Metadata and baselines persist per selected folder. Export records for your own backup; no automatic creator-site checking or compatibility claims.

**Organizer → Transfer mods between computers** adapts selected MIT SyncCrate comparison and disabled-name rules. On the source computer create a verified backup, then copy the entire backup folder (manifest.json and files/) with a drive or your own file-sharing service. Select the destination Mods folder and enter the copied folder path. Verify & preview shows new, matching, conflicting and local-only files. Create verified review copy copies only new/conflicting incoming files to a new folder in private app storage. It rechecks both sides, preserves local disabled names, verifies copied hashes, and writes review.json. Installed files are never replaced or deleted. Incomplete folders retain pending.json and must not be installed. Review dependencies and manually install only after closing the game and making backups. This is not LAN sync, native SyncCrate archive compatibility or a complete merged Mods folder. Keep transfers private and respect creators' permissions.

**Workshop → Tools → Career builder** adapts MIT HistorianCareer track/level templates and reference resolution. Plan up to 20 ranks with pay, schedules and descriptions. Save one draft per collection, import/export plan JSON, or export a ZIP containing editable tuning XML, strings, stable IDs and a completion checklist. The included Cozy Bell Innkeeper is an editable example. Exports are experimental source, not installable mods: SimData, game registration, icons and current-game validation remain development work. Do not put the ZIP in Mods.

Android 0.6.0 and the site include the same career builder. Filesystem scanning, metadata baselines and portable transfers run on desktop only. Existing Bridge/Live 0.2.0 is unchanged.

## Updated in 0.9.0

Notebook search covers title, text and linked Sims, with planned/completed filters and pages of 24. Start from a makeover, build, play-session or MySims business brief. Switching notes/tools or leaving a page warns about unfinished edits; drafts are not automatically saved.

**Workshop → Tools → Troubleshoot** reads supported Sims error reports as local text, groups repeated entries, compares reported builds and lists traceback clues without declaring a culprit. Its manual 50/50 planner remembers grouped candidates and round notes, supports undo, and exports/imports history for the same collection. It never changes Mods files.

**Tools & mod reviews** adds a searchable 12-project directory with explicit inclusion and license states, plus a review queue for existing CC/mod records. Record creator links, installed and observed creator versions, last-check dates and tested game builds in a profile. The queue highlights missing or differing information; it does not scan creator sites or update mods. Android 0.5.0 includes the same tools. See `WORKSHOP-GUIDE.md` for limits. Existing profiles, 1 GB Tray support and Bridge/Live 0.2.0 are retained.

## Updated in 0.8.0

The bundled Workshop now opens with Home, Library, Planner, Tools and More. Create collections and edit local Sims, households, worlds, builds, CC and tasks. Search all records, filter by type/status, sort, archive and restore, and browse 24 records at a time without the previous 300-record cutoff. The dashboard shows progress and next actions. Plan imports have a review step and an export-first option before replacement; record saves detect changes from another window. Android 0.4.0 includes the same workspace. The Tray reader adds search, type/review filters and paginated results across the Hub, desktop and Android. The existing 1 GB limit remains. Bridge and Live remain 0.2.0.

## Added in 0.7.0

Open **SimSync Workshop** for Tray households and lots, supported cover pictures, outfit references, offline story notes with file-based merges, optional local casting AI and SimRipper OBJ previews. **Outfit CC finder** follows supported CASP and GEOM references against your Package inspector scan. Read `WORKSHOP-GUIDE.md` for setup and limits.

World maps now use compact offline images; full-size maps remain in the connected Hub. Existing Bridge and Live mods remain version 0.2.0. No current-patch game compatibility or physical Android test is claimed.

## Added in 0.6.0

- **In-game panel:** updated Bridge 0.2.0 opens native dialogs after a household loads. Use `simsync.panel` to reopen status, household details, Live controls, label export, setup and preferences. See **IN-GAME-GUIDE.md**.
- **Package inspector:** S4TK resource indexes, exact file duplicate groups, possible resource overrides and supported image previews. It never edits or executes mods. Limits and skipped files are visible.
- **Save pictures:** preview candidates, including supported transparent JPEGs through the LlamaLogic-derived converter, and save PNGs. Household matching remains manual.
- **Search everything:** MiniSearch fuzzy/prefix lookup across Sims, households, lots and scanned packages.
- **Sim chat:** SimAI-derived context and prompts with an explicitly enabled local Ollama model. Generated roleplay, no game control. Context uses saved data and fresh same-slot Live observations when available.
- **Integrations:** setup status, licenses, source links and verification limits. Lot 51 Core and Ollama are optional external installs.

### Local chat setup

Install and start Ollama from https://ollama.com/download, then install a local model compatible with your computer. In SimSync open **Sim chat → Find installed models**, choose the model and enable it. Choose a Sim and send a message. This Ollama chat feature does not download models, require an API key or use cloud models. Workshop local casting is a separate opt-in feature that downloads its MiniLM model. It talks only to `127.0.0.1:11434`. Model licenses vary. Chat starts disabled after each app launch. The last 20 messages per Sim and save slot are retained in local `sim-chat.json`, subject to a 50-conversation / 1.8 MB cap. Use Clear this conversation to erase one thread.

## Mod library

Open **Mod library** without selecting a save. Browse to the actual Mods directory, paste its full path, or use the selected save's Mods folder. Click **Start scan**. Scan runs in a worker with progress and cancellation. It reads regular files recursively, streams SHA-256 hashes, and reports exact-copy groups, filename category hints, script depth, archives and empty files. Search and filter the inventory. A partial or canceled scan never means the folder is clean.

Files stay in place. There is no move, delete, rename, extraction, AI classifier or restore-to-Mods command. Game code is never imported or executed by the scanner. Existing top-level folders and supporting files stay together in preservation groups. Matching script/package stems are low-confidence candidates, not complete dependency verification. Duplicate hashes mean equal observed bytes only, not a broken mod, version match, package-resource conflict or safe removal. Hardlinks are identified without estimating reclaimable space.

**Export mobile summary** downloads counts, category totals and scan coverage only. Transfer the JSON to your phone and open **Connected Sims Hub → More → CC & mods → Import desktop summary** in Android 0.4.0, or visit https://anubismods.rangerred221.chatgpt.site/simsync/inventory. The summary view belongs to the connected online Hub; the bundled local Workshop is a separate screen. Import reads the file on your device, sends nothing to the server or AI, and resets when the page reloads. The summary is a dated snapshot, not live mod sync.

### Verified backups and separate-copy restore

Close The Sims 4 and pause cloud folder syncing before creating a backup. Finish a complete scan with no unreadable, linked, excluded or over-limit entries. **Create verified backup** copies every scanned regular file, keeps its relative path, records its hash and group, independently reads the copied bytes again, then checks the source again. Free space is checked before copying. New, changed or missing source files prevent a backup from being marked complete.

The manifest is written last. A canceled or failed copy is marked incomplete and cannot be restored. **Verify backup** rereads each recorded file. **Restore separate copy** first verifies the backup, then copies it into a newly created review directory and verifies that result. It never overwrites any existing file or targets the original Mods directory. Original file content and relative paths are preserved; original permissions, hardlink topology, timestamps, empty directories and filesystem metadata are not recreated. The backup covers regular files in the selected folder, not saves or Tray.

Storage is under `SimSyncBridge/organizer` within the settings folder described below. Full local inventories and backup manifests contain relative filenames, sizes and hashes; mobile summaries do not. Backups remain on the same computer and are not off-device disaster recovery. Incomplete copies remain visible for manual review in app storage; SimSync does not automatically delete them. No pruning policy is enabled.

Limits: 50,000 visited entries, 12 folder levels, 8 GiB per file, 100 GiB read budget. Links, junctions and special files are skipped. Redirected root paths are rejected; explicitly select their resolved real location. Ordinary filesystem changes are checked before and after reading. Pure Node path checks do not provide an OS sandbox against malicious same-user processes swapping directory ancestors. Keep app storage private and avoid using a concurrently changing folder.

The release is tested with disposable synthetic libraries. Native Windows/macOS pickers, platform filesystem behavior, cloud placeholders and real Sims libraries still need device testing before enabling any future destructive operations.

## Live game

The optional SimSyncLive.ts4script exports the current household, lot, selected Sim and supported needs every ~10 seconds. Open **Live game** in the desktop app, then explicitly enable **Share live with Hub** to see observations on Android under **Connected Sims Hub → More → Game sync & Live**. Sharing is off each time the app starts. See **LIVE-GUIDE.md** for installation, commands, limitations and the in-game test checklist. Live observations never replace your plans or saved reports. Current Sims 4 patch compatibility still needs an in-game test.

## Start

1. Install **Node.js 22.13 or newer** from https://nodejs.org/en/download if needed.
2. Extract the entire ZIP outside your Sims Mods folder. Keep its files and map folders together.
3. Windows: double-click **Start-Windows.cmd**. macOS: run **Start-macOS.command**, or open Terminal in the extracted folder and run `node app.mjs`. Linux can use the same command and enter the save path manually.
4. The app opens at a private address on `127.0.0.1`, on a randomly assigned port. Keep its terminal window open. If it does not open, copy the complete private URL printed there, including the fragment after `#`.
5. Choose **Open a save**. Select a detected save, use the native picker, or enter the full path to a current `.save` file. Common Documents and OneDrive locations are checked. Relocated folders are supported.
6. Explore the dashboard, Sims, households and maps. Pairing is optional for local browsing.

This is a runnable portable source package, not a signed EXE/DMG installer. No npm install is needed. Do not run the older helper at the same time.

## Connect your Sims Hub

Open **Connection → Open Sims Hub to pair**. Sign in to your existing AnubisMods site, choose the right collection and create a code using the slot ID supplied by the app. Paste that one-time code into SimSync, then choose **Start sync**.

The app reuses existing SimSync Bridge settings if they are present. You must select the same file and internal slot before starting that connection. Browsing another save never silently changes its pairing. Changing slots requires a new pairing.

Sync is one-way, game → Hub. It sends supported extracted game data and bounded picture candidates. It does not send raw saves or installed CC/mod files. Imported game reports can update automatically; changes to editable planning fields require review in the Hub. Profiles, reference images and finished ZIPs remain there, protected by your existing sign-in. The helper token cannot read those private plans/files.

## Included

- Local dashboard refreshed when the selected save's stable bytes change.
- Sim profiles with saved traits, aspirations, careers and all additional supported reader sections.
- Household members, saved funds and home-lot links.
- All 31 existing Hub world maps, zoom, clickable catalog footprints and an accessible location list.
- A separate saved-neighborhood list for inspecting actual saved lots and residents. Catalog locations are not automatically asserted to match renamed or localized saved lots.
- Activity summaries by game slot, with new/changed/absent record counts and up to 60 named changes per read. Retains the latest 100 reads across all slots locally.
- JSON export of the current extracted snapshot and activity list.
- Read-only Mods/Tray file checks: file counts, script depth, empty files, unextracted archives and repeated filenames. A repeated name is not proof of a conflict. Tray counts are individual files, not households or builds.
- Hub links for your Anubis Save plans, MySims cast, full map tools, uploads, backups and save-aware AI.
- Existing SimSync Bridge helper, optional tuning-label script mod and setup guide.

## What is not included

- Changing a Sim or the game from the app. Live observations require the new optional mod and a game test.
- Native Sims phone integration, voice or game-control tools. Desktop AI chat is generated roleplay.
- A signed desktop EXE/DMG installer, background OS service, LAN/phone access or cloud copy of local activity.
- Definitive mod conflict/compatibility detection or automatic mod downloads.
- Automatic identification of household portraits.
- Full local Hub planning or ZIP mirroring. Open the existing Hub for those features.

Cyberdeck's normal-phone prototype is a separate game-specific integration; it cannot be reused unchanged in The Sims 4.

## Optional game mod

The included `SimSyncBridge.ts4script` is updated to 0.3.0 with the native game panel, diagnostics and stable-slot label export. Install it together with `SimSyncLive.ts4script` in `Mods/SimSyncBridge`. Replace old copies while the game is closed, enable script mods and restart. Read **IN-GAME-GUIDE.md** for installation and controls. Its `simsync.export` command writes internal tuning labels. Those labels can enrich names in the extracted data but are not guaranteed to be the game's translated UI labels.

The dashboard and save reader work without this mod. Its actual in-game compatibility remains unverified until tested on your installed game patch. Windows/macOS native pickers and launchers also require testing on those operating systems.

## Activity and privacy

Game saves and installed packages are read only. The desktop writes a bounded, credential-free status heartbeat beside the Bridge so its in-game panel can detect this app. The app stores its last selected path in `app.json` and summary activity in `app-history.json` inside `%LOCALAPPDATA%/SimSyncBridge` on Windows, or `~/.config/SimSyncBridge` on macOS. Your existing `connection.json` contains a private Hub token. Do not share that folder or its contents. Local file modes are restricted where the OS supports them.

The local server binds only to `127.0.0.1`. It validates the host, browser origin and a random per-launch session token. The Hub bearer token is never returned to the browser. The browser retains only the local session token in sessionStorage so reloading this tab works. Do not share its private URL.

The activity log is not a backup and cannot restore the game. A new app session establishes a baseline. “Absent” refers to an extracted snapshot, not proof of deletion or death. Keep game backups separately; Hub backup tools cover your Hub records.

## Testing the first run

1. Open a save and verify a familiar Sim's name, household and career.
2. Pair the correct Hub collection and start sync.
3. Make a recognizable change in The Sims 4 and save. Wait for the app's snapshot time to change, then check Save activity.
4. In the Hub, open Game sync, review the received snapshot and confirm the same changed value.
5. Record the game version and results in the Hub's existing in-game test checklist. Report missing or incorrect data with the affected section, not your connection token.

## Troubleshooting

- **App unavailable after reopening a bookmark:** relaunch and use the new private address. Ports and tokens change each launch.
- **Native picker does not work:** paste the full `.save` path instead.
- **No change yet:** save in game; allow two stable file checks. Raw saves must be 96 bytes–128 MB. Unsupported data is identified in reader notes.
- **Paired save differs:** stop sync, select the original paired file or create a fresh pairing for the selected slot.
- **App opens but Hub sync fails:** inspect Connection, then your Hub's Game sync panel. Revoked or expired tokens need a new code.
- **Another helper running:** stop the old bridge before starting sync here.
- **Mod scan partial:** scans stop at 50,000 entries or 12 subfolder levels and display a partial-results message. Symlinks are skipped. The scan never certifies a mod is safe or compatible.

## Uninstall

Close SimSync, revoke its connection in Sims Hub and remove the extracted app folder. Remove the optional script mod separately if installed. Remove `app.json`, `app-history.json` and `sim-chat.json` to clear local app data. Removing all of the SimSyncBridge settings folder also removes your prior bridge connection. Your game saves and Hub plans stay intact.

## Development

Source: `companion/simsync-app` in the AnubisMods repository. Build: `node companion/simsync-app/build.mjs`. Set `SIMSYNC_PYTHON37` to a Python 3.7 interpreter to compile changed mod sources. The builder bundles runtime dependencies and their license texts. Run `node tests/simsync-app.mjs`, `node tests/simsync-integrations.mjs`, `node tests/simsync-live.mjs` and the Python mod/panel tests after building.

Unofficial fan tool, not affiliated with EA or Maxis. Game artwork belongs to its respective owners. See `THIRD-PARTY-NOTICES.md` and the per-world source links in the app.

## 0.4.1 diagnostic update

Live diagnostics shows the expected Mods folder, installed copies and the last mod load or command message. Live mod 0.1.1 adds `simsync.ping`, immediate command acknowledgement and error details. It uses the stable game slot GUID when available. The save reader can recover a zero embedded slot from a standard save filename, with a warning to verify it against the running game. These changes have automated coverage; actual game compatibility still needs testing.


## Full TrayTrim integration

Desktop 0.12.0 includes all TrayTrim 0.4.0 source, its export engine and its optional original Qt workspace. Open **Tray & CC** for setup, compact and batch exports, dependency review, ZIP checks and history. Python 3.12+ is required. The full workspace has a separate, explicit PySide6 setup. **In-game Gallery upload → TrayTrim** uses the engine for the existing Bridge menu and private ZIP uploads. The EA Gallery button is still unfinished. See [the TrayTrim guide](traytrim/README.md) and [feature coverage](traytrim/FEATURES.md).
