Version 4.7 Release [Active]

Changelog - Version 4.7

[4.7] - 2026-06-10

---

Fixed

• World model flat path generation — the flat candidate in _world_base_candidates() now correctly drops the c_<name> subfolder when building the w_models/ path. Previously generated w_models/c_<name>/w_<name> (wrong); now correctly generates w_models/w_<name>. World models for flat-structure weapons like the minigun now pack correctly.
• Windows pip PATH warning — pip auto-installs now pass --no-warn-script-location so the harmless but alarming PATH warning no longer appears on first run.
• Custom path filename — custom output paths with no .vpk extension now have the generated filename appended automatically, consistent with folder path behaviour.
• Invalid character check — expanded to catch shell-special characters (|, &, ;, etc.) in addition to null bytes and non-printable characters. Now also applied correctly in CLI mode and dry-run paths.
• Ornament models in weapon search — c_xms_festive_ornament and similar schema-less non-weapon models are now excluded via a path-based blocklist, preventing them appearing in festive weapon searches.

---

Changed

• All-class items with no class-specific variants now appear in all class searches rather than being silently excluded.

---

Added

• Schema caching — items_game.txt is parsed once and saved to output/schema_cache.json. Subsequent runs load the cache instead of re-parsing, significantly reducing startup time. Cache automatically refreshes if TF2 updates items_game.txt.
• Startup risk warning — shown on every run. First run requires typing agree before continuing. Covers VAC risk, competitive league policies, and using the tool while TF2 is closed. Retries on wrong input rather than exiting.
• Acknowledgement flag — stored in output/.acknowledged as a SHA256 hash rather than plain text. Not to hide anything (source is fully open); provides light tamper-resistance for liability purposes. Verifiable with: hashlib.sha256(b"tf2autoswap_acknowledged").hexdigest()

---

Author Notes

4.7 ended up being a bigger release than planned. What started as a world model path fix turned into a proper testing session that caught several issues that had slipped through — the ornament filter, the invalid character check missing CLI paths, and the flat path bug being more broken than originally thought.

The risk warning and acknowledgement system were added this release for liability reasons. If you're wondering about the hashed flag file — it's documented in the changelog, the source is fully readable, and the verification snippet is right there. Nothing is hidden, it's just not plain text for tamper-resistance purposes.

Also switching to GPL v3 this release to align with the mods.tf source code license, making future integration work cleaner. This was always the plan before v5 — it just happened a little earlier than expected.

Thanks to everyone who's downloaded, tested, or given feedback so far. Still very much learning as I go.

Version 4.6 Release [Legacy]

[4.6] - 2026-06-08

Fixed

World model detection — derive_world_base() now correctly derives the flat w_models/w_<name>.mdl path structure TF2 uses, rather than the nested folder structure that was assumed. World models now pack correctly for standard weapons.
All-class cosmetic class filtering — per-class variants of all-class items (e.g. the Demoman variant of the Cozy Camper) no longer appear in searches for other classes. Handles shortened path names (_demo, _engi, _solly etc).
Duplicate weapon search results — weapons appearing from multiple VPK paths with the same basename are deduplicated before displaying the pick list.
Weapon search clutter — animation rigs, arm models, festivized variants, and seasonal reskins are filtered from weapon search results by default. Searching for a variant term directly (e.g. festivizer) still shows them.
Path validation — custom output paths are validated before building. If a path isn't writable, the tool falls back to the output folder and tells the user, rather than writing to an unknown location silently.
Subfolder mod scanning — list/remove mods now scans subfolders within the output directory, displayed separately from root-level mods.

Added

Keyword normalisation — search keywords are lowercased, spaces converted to underscores, and punctuation (apostrophes etc) stripped before matching. crusader's getup now finds hwn2015_firebug_suit correctly.
Friendly name reverse search — if a keyword returns no VPK hits, the tool searches schema friendly names and retries with the matching internal stem. Works for both cosmetics and weapons.
Auto-select single results — if a search returns exactly one match it is selected automatically with a confirmation line, skipping the pick prompt.
Menu selection confirmation — choosing cosmetic swap or weapon swap from the main menu prints a confirmation line before the first step, so a wrong choice is immediately obvious.
Smarter "did you mean" — suggestions are pre-filtered to stems sharing the same starting characters before running difflib, reducing unrelated matches.
Melee world model note — when no world model is found for a melee weapon, the message now clarifies this is expected behaviour rather than an error.

Still learning how to use Github so apologies for any confusion in layout / documentation especially of past releases & thank you for your support!

Version 4.5 [Legacy]

[4.5] - 2026-06-08

Added

Slot compatibility warnings — clip_warning() now warns on any equip region mismatch between source and target cosmetics, not just head replacements. If two items cover different areas of the player model, a warning is shown at the confirm step so the user can make an informed choice before proceeding.
Preloader write warning — writing directly to the Casual Preloader folder now shows a hard warning explaining the risk and requires typing yes to confirm. This applies in both interactive mode and CLI (--to-preloader, custom paths that point inside the preloader folder).

Changed

Output folder and log file are now self-contained within the tool folder rather than writing to ~/tf2_swaps/. Built VPKs go to output/ and the log file sits alongside the scripts. This makes the tool fully portable — zip the folder and everything moves with it.

Version 4.4 [Legacy]

[4.4] - 2026-06-07

Added

Weapon swaps — swap any TF2 weapon model for another, client-side.
Guided 5-step flow: class → loadout slot → weapon to replace → replacement → confirm & output.
Swaps both viewmodel (c_models) and worldmodel (w_models) in one operation. If no worldmodel is found for a weapon, the swap completes with the viewmodel only.
Slot mismatch warnings — warns if source and target are different loadout slots (e.g. primary into melee), which can cause animation or behaviour issues in-game.
Output to VPK or preloader addon folder (native installed format), identical to cosmetic swaps.
--weapon CLI flag — routes python3 tf2autoswap.py <source> <target> --weapon to weapon mode.
--list --weapon lists weapon matches with slot labels.

Changed

Interactive menu expanded from 3 to 4 options: cosmetic swap / weapon swap / mods / installed.
ItemInfo in tf2_schema.py gains three new fields: item_slot (e.g. "primary"), item_type ("cosmetic", "weapon", "unknown"), and animation_risk (True for melee weapons).
weapon_swap_warning() added to tf2_schema.py (parallel to clip_warning()).

---

Version 4.3 [Legacy]

[4.3] - 2026-06-07

Added

Output to the preloader now writes the preloader's native installed addon format (a folder with extracted files plus a mod.json manifest), matching what the preloader creates when a VPK is dragged in. Mods sent to the preloader appear ready to enable with no manual import step.
Custom paths and --out that point inside the preloader folder are detected and written in addon format automatically.
--list-installed now lists native addon folders (detected via mod.json) as well as loose .vpk files, flagging each from TF2autoswap.
Dry run / preview — --dry-run on the command line shows exactly what would be built (file sizes, destination path) without writing anything. In interactive mode, a compact preview shows at the confirm step.

Changed

Outputting elsewhere (outside the preloader) still produces a single .vpk — the portable form for sharing.

Version 4.2 [Legacy]

[4.2] - 2026-06-07

Added

Output directly to the preloader addons folder, removing the manual move step.
A "Preloader addons folder" choice at the output step in interactive mode.
A --to-preloader command-line flag.
Passing a folder to --out now works — the filename is added automatically.
--version flag, and the version now shows in the interactive header.

Fixed

Giving a folder as the output path no longer crashes — the tool appends the generated filename instead of trying to write the VPK as a directory.

Version 4.1 [Legacy]

[4.1] - 2026-06-07

Changed

Renamed the project to TF2autoswap.
New output filename format using friendly names: <Target> replacement mod (<Source>)_TF2autoswap.vpk.

Added

List and remove mods you've built — interactive menu option and --list-mods.
List .vpk addons present in the preloader folder (--list-installed), with your own files flagged via the _TF2autoswap signature.
Interactive mode now opens to a top-level menu: swap / manage mods / list installed.

Author Notes

Initially referred to as version 4.0 beta hence the change in file name, later updated to match with formatting for version numbers (plan was going from version 4 to 5 hence the per digit increases before this point but i realized the version number would balloon out of control if i did that & adjusted accordingly).

Version 4.0 [Legacy]

[4.0-beta] - 2026-06-07

Changed

Split the code into a clean core (tf2_core.py) and interface (tf2_swap.py) so future frontends (TUI/GUI) can sit on top without a rewrite. The core is interface-free — no print() or input() calls. All user interaction stays in the interface layer.
Errors in core are now raised as typed exceptions (SwapError, TF2NotFound, ModelNotFound, BuildError) and caught by the interface layer.

Added

Error logging and build history written to ~/tf2_swaps/tf2autoswap.log.

Author Notes

The architectural refactor that made everything after it possible. Separating the core logic from the interface meant any future frontend — TUI, GUI, web app — could sit on top without touching the engine. This is the version that turned a script into a proper project.

Version 3 [Legacy]

[3.0] - 2026-06-07

Added

Schema parsing via tf2_schema.py — reads TF2's items_game.txt to show friendly item names alongside internal keywords during search.
Head-clip warnings — warns at the confirm step when a head-replacement model is placed on a slot that doesn't hide the default head, which would cause the default head to clip through the replacement.
tf2_schema.py is optional — the tool continues without it, just without names and warnings.
Prefab inheritance resolved in schema parsing — most items in items_game.txt inherit fields from parent prefabs, the resolver merges these correctly so all items are indexed with the right data.

Author Notes

v3 was the quality-of-life update that made the tool feel polished. Before this, users had to know internal keywords to search. After this, you could search "towering pillar of hats" and the tool would show you "The Towering Pillar of Hats" rather than a raw file path. The head-clip warning was also the first safety feature — a direct response to the original use case of swapping hats, where clipping was the most common mistake.

Outdated, consider any releases past this point as purely uploaded for documentation of development. Do not use.

Version 2 [Legacy]

[2.0] - 2026-06-07

Added

Interactive guided mode — run with no arguments for a 5-step flow: class → cosmetic to replace → replacement source → confirm → output location.
Import custom models from disk (Gamebanana / custom work), automatically bundling a sibling materials/ folder so custom textures come along.
"Did you mean" typo suggestions when a search returns no results.
Search now treats spaces and underscores the same — hot air finds hot_air.
Cross-platform TF2 path detection — Linux, Windows, and macOS.
vpk library auto-installs on first run if not present.
--import flag for importing local .mdl files from the command line.

Author Notes

The jump from v1 to v2 was where it became a real tool rather than a script. Interactive mode made it accessible without needing to know the internal keywords, and cross-platform support opened it up beyond Linux. The materials bundling also meant Gamebanana downloads would work out of the box.

Outdated, consider any releases past this point as purely uploaded for documentation of development. Do not use.