Real-time Escape from Tarkov weapon build simulator and community build sharing platform

English · 中文

EFTForge is a full-stack Escape from Tarkov weapon build simulator and community platform. It provides a 3D builder, a dual-view 2D workbench, real-time stat calculations, live composite build preview images, flea/trader price fetching, a combo calculator, attachment graphing, user profiles, build comments, and a community build publishing system with leaderboards. In-game data is sourced from tarkov.dev and SP-Tushonka.

• Build your weapon in 3D, now the default view; switch back to 2D anytime (mobile stays 2D)
• Click a slot on the model to pick a part, right click to remove it
• Compact Picker - pick parts from an in-game style dropdown
• Stats and price panel you can drag anywhere
• Sight Picture - look through your sights and try aiming down sights
• Range - change the target distance, or swap the background for a green screen
• Hide UI for recording
• Try out lights and lasers
• See the muzzle smoke and flash when firing
• Magazines show the ammo you selected
• A short tour the first time you open it

• Grid view - attachment slots arranged spatially on a 2D canvas mirroring the physical weapon layout (barrel, stock, optics, grip, etc.), grouped into zones (Upper, Lower, Left, Right, Extras)
• List view - traditional recursive attachment tree with full slot and allowed-item resolution
• Build State Intelligence - gun display name syncs to a saved build name when the installed attachments match it exactly
• Build Image Export - Export button in the workbench toolbar renders the current build to a PNG for saving or sharing

• Attachment Favorites - star button on each attachment row to bookmark items; favorites sort to the top and can be filtered via a header toggle; stored in localStorage
• Combo Calculator - BFS search across all valid attachment combinations for a slot, ranked by a chosen stat; results stream live with a progress indicator; installs the full combination in one click
• Attachment Graph - scatter plot of all attachments for the current slot on two configurable axes (V-Recoil, H-Recoil, Ergo, Recoil Modifier); zoom, pan, cluster cycling; custom cross-weapon graphs; exportable at 4x resolution

Constraint-based weapon build solver (MILP, HiGHS backend) that fills every attachment slot at once instead of tuning one at a time.

• Build tradeoff curve - generates a whole curve of alternative builds for the selected weapon (ergonomics/recoil, ergonomics/price, or recoil/price) instead of a single result; solves stream in live and render on the chart step by step. Adjust sampling resolution, zoom/pan the chart, select a point to inspect its parts, and apply it to the workbench. Uses the configured constraints, attachment filters, and trader access; incomplete searches retain available builds.
• Hard constraints - budget limit, min ergonomics, min magazine capacity, min sighting range, max MOA, suppressor requirement, and prevent overswing
• Attachment Filtering - force-include or ban specific mods, then re-optimize; results can also be locked or banned per part directly from the build manifest
• Weight presets - save and reuse custom priority-slider setups, alongside built-in presets (Balanced, Min. operable, Performance, Recoil+, Ergo+)
• Use TrueErgo - optimize for how far a build is from overswing, not just raw ergo
• Include unpriced parts - also consider parts you can't buy from traders or the flea market; they never count as free
• Receiver vs. Factory Preset costing - compares buying the base receiver against buying the weapon's factory preset, and prices the result off whichever is cheaper
• Respects the same trader loyalty levels, flea market toggle, and player level filters as the rest of the app
• See Credits & Acknowledgements for the original creator of the optimizer feature

• Real-time stats: ergonomics, recoil, weight, arm stamina, sighting range, etc.
• TrueErgo - how much ergo your build has left before it overswings, using the game's own rule
• Arm stamina and aim sway match the game's own formulas
• Loudness stat for muzzle devices and barrels
• Full magazine ammo weight modeling
• Real attachment conflict detection (conflictingItems + conflictingSlotIds)

• Composite gun image generated in real-time as attachments are added or removed
• Drawn in-house by Kitbash!, see its section below for how it works
• Factory configs and bare guns use static tarkov.dev images directly
• Kitbash! Image Generation toggle to turn generation off

• Per-item cost breakdown for every attachment in the current build
• Cheapest source auto-selected between trader and flea market
• PvP / PvE flea price cache toggle (separate caches, no re-fetch on switch)
• Per-trader loyalty level gating (LL1-4) for Prapor, Skier, Peacekeeper, Mechanic, and Jaeger
• Price chips visible in the attachment table at a glance
• Attachment selector Buyable filter - hides attachments your traders cannot currently sell
• Quest unlock notes on attachments that require completing a trader task

• Surfaces item stat changes detected automatically during daily server data syncs
• Each entry shows old/new values, percentage change, and the date detected
• Shows the last 7 days by default; pick any earlier day to see its changes
• Panel header shows when the data was last synced

• Quasi-local identity system: your profile token lives in localStorage with no registration, password, or email required
• Upload or update an avatar (resized to 128x128 JPEG, stored server-side)
• Edit your display name; author avatar and name appear on every community build card
• Account transfer flow to relink builds and comments when moving to a new device or browser

• Publish, browse, and load community-submitted builds
• Auto-generated composite preview images and profile avatars hosted on Gitee https://gitee.com/morph1ne/eftforge-assets/
• Build Comments - per-build comment thread; deletable by the author or an admin
• Build Tags - up to 5 preset tags per build (e.g. Budget, Recoil, Meta); tag filter row in the community list collapses automatically when no filters are active
• My Community Builds tab in the builds dialog to view and reload your own published builds
• Voting (like/dislike) on builds and individual attachments
• Leaderboard - top 10 trending / top 50 all-time for builds; top 20 / top 100 for attachments; filterable and sortable
• Featured build system curated by admins
• Build load count tracking
• In-app notifications for admin moderation actions
• Admin tools: feature, unlist, ban, comment moderation, announcements

• Local saved builds (up to 500 per device)
• Build serialization and LZ-String compression for build sharing and ?build= URL codes
• Session restore on page reload - recovers your last active build state automatically
• Deep link support: external tools can pre-load a build directly via the ?build= query parameter

• English and Chinese (Simplified) with automatic fallbacks
• Chinese item name translations stored alongside source data

Custom Tarkov builds, rendered in milliseconds.

_{The rifle in the logo is a real build drawn by Kitbash! Open it in EFTForge}

Kitbash! is EFTForge's in-house rendering engine, made by Morph1ne, the creator of EFTForge. It has two parts:

• 3D engine - runs the 3D Builder
• 2D sprite compositor - draws every build image on the site: the live workbench preview, build tab hover previews, optimizer result previews, exported PNGs, community build cards, etc.

Each version of Kitbash! has a codename:

• Kitbash! Sirius - the first version, the 2D sprite compositor only
• Kitbash! Arcadia - the current version, adding the full 3D engine

Kitbash! is a separate standalone project. Its repository is private for now, and may be open-sourced in the future if there is enough demand!

• Every weapon and attachment is rendered once, offline, from the game's own models into a sprite with a depth map
• At runtime a build is assembled by stacking those sprites at 2D offsets and depth testing them, so rendering needs no game client, GPU, or browser
• This works because the game's inventory icon camera is orthographic: a part's silhouette never changes with position, and its place on screen follows directly from its 3D mount point
• The compositor runs in process inside the FastAPI backend (Pillow) and outputs WebP at twice the game's inventory icon size

• Full magazines - with Assume Full Magazine on, magazines are drawn loaded with the selected ammo and underbarrel grenade launchers with their round, just like the game
• New weapons - guns tarkov.dev has no image for yet are drawn by Kitbash! from their factory preset, or as a bare receiver
• Missing parts - an attachment Kitbash! can't draw yet is left out of the image instead of failing the whole build, and a notice tells you some parts aren't shown
• Community build cards - drawn once and stored permanently on Gitee; since a stored card sticks around, it waits until Kitbash! can draw every part in the build

• Rendered images are cached per exact build tree and loaded ammo, so revisiting a build is instant
• Decoded sprites are cached separately per worker process (KITBASH_CACHE_MB, 128 MB by default)

EFTForge is also available as a downloadable Windows app - the same workbench and stat calculations running natively on your machine via a local backend, with an optional connection to the live community servers. Useful if you're far from our hosting or have a slow connection to it, or if you just want everything to keep working when the site's services are temporarily down (community features excluded until it's back). Note that an internet connection is still required either way, since item data and images are fetched directly from tarkov.dev, independent of EFTForge.com.

• Download: GitHub Releases - or the Gitee mirror if GitHub is slow or blocked for you
• Details: see desktop/README.md for architecture, local development, and build instructions
• The 3D builder needs Connected to EFTForge.com mode; Fully local mode uses 2D only

• Python 3.10+
• A modern web browser (Chrome, Firefox, Edge, etc.)

git clone https://github.com/SouthHorizons76/EFTForge.git
cd EFTForge

Open launch.bat in a text editor before running anything.

Browser path - the launcher opens browser tabs automatically. The default path targets Chrome on Windows. If you use a different browser, update this line:

start "" "C:\Program Files\Google\Chrome\Application\chrome.exe" --new-window ...

Examples for other browsers:

# Firefox
start "" "C:\Program Files\Mozilla Firefox\firefox.exe" -new-window ...

# Microsoft Edge
start "" "C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe" --new-window ...

Install Python dependencies inside the backend/ folder:

cd backend
python -m venv venv
venv\Scripts\activate
pip install -r requirements.txt
cd ..

cd backend
copy .env.example .env

Edit backend/.env. These two variables are required - the server will refuse to start without them:

IP_HASH_SECRET=any-random-string-here
ADMIN_API_KEY=your-admin-key-here

For local development any non-empty values work. For production use strong random values (openssl rand -hex 32).

Full .env reference (all optional except the two above):

DATABASE_URL=sqlite:///./tarkov.db
RATINGS_DB_URL=sqlite:///./ratings.db
BUILDS_DB_URL=sqlite:///./builds.db
CORS_ORIGINS=http://127.0.0.1:5500
ENABLE_API_DOCS=0            # set to 1 to enable /docs and /redoc
TRUSTED_PROXY_IPS=127.0.0.1,::1

# Community build image generation (optional, used only on live prod.)
GITEE_TOKEN=                 # Gitee personal access token for uploading build card images
GITEE_DRY_RUN=0              # set to 1 to simulate uploads without writing to Gitee
DISABLE_BG_MIGRATE=0         # set to 1 to disable the background image migration worker

launch.bat

This single .bat file will:

• First run: build the database and sync all item data from tarkov.dev before starting, since there's nothing to serve yet
• Subsequent runs: start the FastAPI backend immediately against your existing local database, then re-sync tarkov.dev data in the background
• Start the FastAPI backend at http://127.0.0.1:8000
• Serve the frontend at http://127.0.0.1:5500
• Open your browser to both

The site is usable as soon as the backend console shows "Application startup complete". If the background sync finds new data, a toast prompts you to refresh; otherwise nothing changes and you keep working on the data you already had. That's it!

3D builder: locally, the 3D view needs the Kitbash! viewer running on http://127.0.0.1:8765. Without it, the builder uses 2D.

Note: sync_tarkov_dev.py is called automatically by launch.bat, which calls reset.py. Avoid running it directly during local development, it is only used on the live production server for manual out-of-cycle resyncs.

The backend runs at http://127.0.0.1:8000 by default. Interactive docs are available at /docs when ENABLE_API_DOCS=1 is set in .env.

External tools can deep-link directly into EFTForge with a pre-loaded build via the ?build= URL parameter:

https://eftforge.com/?build=<share_code>

The loader accepts three share code formats: dictionary based 3. codes, full-ID compact 2. codes, and legacy LZ-String codes. EFTForge generates the shorter of 3. and 2. for each build. External projects can generate either compact format by following the encoder in frontend/modules/build-manager.js. 3. codes also require the frozen item and slot dictionary in frontend/data/build-code-catalog-v1.js; see scripts/BUILD_CODES.md for the format and dictionary rules. Use 2. when an ID or slot is absent from the dictionary. Neither compact format requires a per-build server record.

For the simplest integration, external projects can still generate a legacy code with LZ-String's compressToEncodedURIComponent(JSON.stringify(payload)). All three formats represent the same payload:

{ "v": 1, "g": "<gunId>", "p": [["slotId", "itemId"], ...], "a": "<ammoId>", "ua": "<ubglAmmoId>" }

The a and ua ammo fields are optional. EFTForge will auto-load the build on page load and strip the parameter from the URL. Item IDs must match EFTForge's tarkov.dev item IDs.

EFTForge's TrueErgo grew out of the EvoErgo concept, originally developed by SpaceMonkey37. TrueErgo replaces EvoErgo's fitted curve with the exact overswing rule the game uses, but the idea of judging ergonomics together with weight started there. This project would not have been possible without SpaceMonkey37's foundational theory.

The constraint-based build optimizer (MILP solver, priority weighting, budget/trader-level filtering) is a native reimplementation inspired by AhaiMk01's Tarkov Weapon Mod Optimizer.

See CONTRIBUTING.md for local dev setup, lint/test commands, and code style. Security vulnerabilities should be reported per SECURITY.md rather than as public issues.

EFTForge is licensed under the GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later). If you distribute a modified version, or run one as a service that other people use over a network, you must release its complete source code under the same license and keep the attribution to EFTForge. See NOTICE for the attribution requirement and for contributions that remain under the MIT License.

Versions released before the switch to the AGPL remain available under the MIT License.

EFTForge and Kitbash! are fan-made projects and are not affiliated with Battlestate Games. In-game data is sourced from tarkov.dev and SP-Tushonka.