FCT Blueprints Decoder/Encoder

A production-practical, zero-backend utility for Factorio players who need to inspect blueprint payloads, tweak JSON, update blueprint book metadata, and ship the encoded string back into the game loop fast.

Important

This project is designed as a client-side tool. All transformations happen in your browser session.

Table of Contents

• Features
• Technology Stack
• Technical Notes
  • Project Structure
  • Key Design Decisions
• Getting Started
  • Prerequisites
  • Installation
• Testing
• Deployment
• Usage
• Configuration
• License
• Community and Support
• Support the Development

Features

• Blueprint decode/encode pipeline: transforms Factorio blueprint strings into readable JSON and back.
• In-browser JSON editing via CodeMirror, including syntax-aware editing and readable formatting.
• Search/replace workflow for large JSON payload surgery.
• Blueprint book support with dedicated metadata editing (label, description, active icon set).
• Icon tooling with selectable icon data mapped to game entities/items.
• Local history cache for recently processed blueprint payloads.
• Clipboard export path for encoded results to quickly paste back into Factorio.

Tip

If you’re iterating on megabase templates, use history + search/replace together to do bulk JSON edits with less copy-paste churn.

Technology Stack

• Languages: HTML5, CSS3, JavaScript (ES6+)
• Editor component: CodeMirror 5 (CDN delivered)
• Execution model: pure client-side browser runtime (no Node.js service, no backend API)
• Data handling: browser memory + local persistence for history
• UI style: custom Factorio-inspired theme and layout

Technical Notes

Project Structure

.
├── index.html            # App shell, UI sections, tabbed layout
├── style.css             # Theme, layout, and component styling
├── script.js             # Decode/encode logic, editor behavior, history, book metadata tooling
├── README.md             # Project documentation
├── CONTRIBUTING.md       # Contribution process and engineering rules
├── CODE_OF_CONDUCT.md    # Community behavior expectations
└── LICENSE               # GPL-3.0 license

Key Design Decisions

• Static-first architecture: the app runs from plain static files, so contributors can debug quickly without complex setup.
• Client-side processing: blueprint strings are transformed locally, reducing operational overhead.
• Single-script orchestration: core logic is concentrated in script.js for direct maintainability in a lightweight repo.
• CDN-hosted dependencies: fast bootstrap, but contributors should be aware of third-party availability assumptions.

Note

Because dependencies are CDN-based, fully offline usage requires vendoring those assets manually.

Getting Started

Prerequisites

You only need:

• A modern browser (Chrome, Edge, Firefox, or Safari latest stable).
• Optional for local serving: Python 3.x or any static file server.
• Optional for contribution workflows: Git.

Installation

# 1) Clone repository
git clone https://github.com/<your-org-or-username>/blueprints-book-rich_text.git
cd blueprints-book-rich_text

# 2) Quick-start: open directly (works for most local use-cases)
# macOS:
open index.html
# Linux:
xdg-open index.html
# Windows (PowerShell):
start index.html

# 3) Recommended: run via local static server (avoids browser policy edge-cases)
python -m http.server 8080
# Then open http://localhost:8080

Testing

This repo currently has no dedicated automated test suite, so validation is execution-based.

# Basic syntax sanity check
node --check script.js

# Serve and run manual QA checklist
python -m http.server 8080
# 1) Decode sample blueprint
# 2) Edit JSON and re-encode
# 3) Validate blueprint book metadata editing
# 4) Verify copy/export behavior

Warning

If you make parser-related changes, always test both single blueprints and blueprint books. They exercise different paths.

Deployment

This project is deployable as static assets.

Option A: GitHub Pages

1. Push repository to GitHub.
2. Enable Pages from repository settings.
3. Select branch and root folder.
4. Publish.

Option B: Static hosting (Netlify, Cloudflare Pages, Vercel static)

• Build step: none
• Publish directory: repository root
• Cache policy: default static caching is usually fine

Option C: Containerized static serving

# Example minimal nginx-based static deployment flow
# (Dockerfile not included in this repo by default)
docker build -t fct-blueprints-web .
docker run -p 8080:80 fct-blueprints-web

Usage

# Decode/Encode Flow
1) Paste blueprint string into "Blueprint Decode/Encode" input.
2) Click Decode.
3) Patch JSON in the editor (or run search/replace).
4) Click Encode.
5) Copy encoded output and import into Factorio.

# Blueprint Book Flow
1) Switch to the blueprint book tab.
2) Paste encoded book string.
3) Click Decode Book.
4) Edit label/description/icons.
5) Re-encode and copy result.

Caution

Invalid JSON edits will block re-encoding. Keep JSON structurally valid after modifications.

Configuration

This project does not require a .env file out of the box.

Runtime behavior is currently configured by:

• Values hardcoded in script.js (icons catalog, metadata handling rules).
• UI/layout definitions in index.html and style.css.
• Browser runtime context (storage, permissions, clipboard support).

If your team needs environment-specific behavior, add a config layer (for example config.json) and load it during app bootstrap.

License

This project is distributed under the GNU GPL v3.0 license. See LICENSE for legal details.

Community and Support

Project created with the support of the FCTostin community.

Support the Development

Contacts

• GitHub: OstinUA
• Team page: FCTostin-team
• Contribution process: see CONTRIBUTING.md.