space-age-easy-mode

Imported from andretosin/space-age-easy-mode (AGENTS.md). Install upstream with npx skills add andretosin/space-age-easy-mode. Copyright stays with the author.

AGENTS.md — Maintainer guide for Space Age Easy Mode

This file is a handoff guide for any AI assistant (or human) maintaining this mod. It captures the domain knowledge, prototype gotchas, and workflow conventions used to build the mod so far. Read it before making changes.

1. What this mod is

Space Age Easy Mode is a Factorio mod that reduces grind and speeds up progression by buffing existing entities. Key facts:

• Data-only. All logic lives in data-updates.lua. There is no control.lua, no runtime scripting, no events, and no custom prototypes with their own names.
• It modifies existing vanilla / Space Age prototypes in data.raw, generically (iterating by prototype type, never hardcoding entity names).
• Target: Factorio 2.0 with optional Space Age (? space-age dependency).
• Because it only tweaks data.raw, the only user-facing strings are the mod name and description (see Localization).

Repo layout

2. How data-updates.lua is organized

It runs after all mods' data.lua/data-updates.lua, so every entity already exists and can be patched. The file is split into labelled feature blocks:

• Helpers — small local functions (see below).
• FR-1: Global Machine Buff — base speed/productivity/consumption on productive machines.
• FR-2: Module Rebalance — doubles module effects.
• FR-3: Drone Buff — 2× robot speed and cargo.
• FR-4: Power Generation Buff — 2× power for generators/solar/fusion/lightning; lightning-rod range; accumulator capacity/throughput.
• FR-5: Roboport Upgrades — 2× radius, ×4 charging slots + energy.

Helpers (reuse these; don't reinvent)

• multiply_energy(s, m) — multiplies the numeric part of a Factorio Energy string (e.g. "300kW" → "600kW"). Use for any buffer_capacity, *_flow_limit, production, charging_energy, etc.
• add(a, b) — (a or 0) + b.
• get_bonus(v) — reads an effect value that may be a number or a {bonus=n} table.
• has_flag(entity, flag) — true if entity.flags contains flag (e.g. "player-creation").
• double_effectivity(prototype) — doubles prototype.effectivity if present.

The general method to add a buff

1. Find the real prototype in the installed game files (don't guess field names) — see §9 for paths. grep for type = "<prototype-type>".
2. Confirm field semantics at https://lua-api.factorio.com/latest/ (prototype pages).
3. Add a block: if data.raw["<type>"] then for _, e in pairs(...) do ... end end.
4. Reuse multiply_energy for Energy strings; multiply plain numbers directly.
5. Gate with has_flag(e, "player-creation") when a change should only affect player-buildable entities (see the lightning-rod gotcha).
6. Iterate generically — never hardcode entity names.

3. Buffs currently implemented (and the fields they touch)

4. Factorio prototype knowledge & gotchas (hard-won)

4.1 Roboport charging — the big one

• charging_offsets is an array of {x, y} positions where robots park to charge. It sets both the slot count and the positions — but only when charging_station_count == 0.
• If you set charging_station_count to a non-zero value, the engine ignores charging_offsets and sends every robot to stationing_offset (the port centre). Result: all robots charge stacked on one pixel. This is a trap — do not raise charging_station_count.
• Vanilla roboport: charging_offsets = {{-1.5,-1},{1.5,-1},{1.5,1},{-1.5,1}}, stationing_offset = {0,0}, no charging_station_count.
• To add more charging slots: generate more charging_offsets and leave charging_station_count at 0/nil. Spread them evenly on a ring (not tight clusters) so charging robots don't visually overlap. The current code puts the ×4 slots on a ring whose radius auto-scales to keep ~0.85 tiles between robots.
• Robots waiting to charge hover at their current position within charge_approach_distance — you can't neatly arrange the queue, only the chargers.

4.2 Lightning rods = lightning-attractor

• Two player rods: lightning-rod (efficiency 0.2, range_elongation 15) and lightning-collector / advanced (efficiency 0.4, range_elongation 25).
• range_elongation is the lightning collection range. Double it for 2× range.
• Gate on player-creation. There is also a fulgoran-ruin-attractor (a decorative world entity, efficiency 0) — do NOT change its range/gameplay. The power buff (efficiency/energy) is applied to all attractors but is a no-op on the ruin (efficiency 0); only the range buff needs the flag gate.

4.3 Accumulators

• Type accumulator, everything lives in energy_source (type electric): buffer_capacity (storage), input_flow_limit (charge rate), output_flow_limit (discharge rate). Vanilla: 5MJ, 300kW, 300kW.

4.4 Energy strings & effects

• Energy values are strings with units ("500kW", "100MJ"). Never do math on them directly — use multiply_energy.
• Machine base bonuses go in effect_receiver.base_effect (plain numbers, not {bonus=n} tables). Accumulate onto existing values so other mods are respected.
• Module effect fields can be {bonus=n} tables or plain numbers — use get_bonus.

5. Localization

• Data-only mods only need locale/<code>/info.cfg with [mod-name] and [mod-description] keyed by the internal mod name (space-age-easy-mode).
• Files must be UTF-8 without BOM. Verify after writing (a BOM can break the first [category] header).
• Use Factorio's locale folder codes: en, de, ru, fr, es-ES, zh-CN, ja, pl, cs, pt-BR, uk (note the hyphens: es-ES, zh-CN, pt-BR).
• Keep the expansion name "Space Age"; translate the rest of the title/description.
• The Mod Portal listing shows the info.json (English) description; the locale files only change what's shown in-game once the mod is installed and the game language matches.

6. Verify against the real game, don't guess

Before touching a prototype, read its actual definition in the installed game:

• Base: C:\Program Files (x86)\Steam\steamapps\common\Factorio\data\base\prototypes\
• Space Age: ...\Factorio\data\space-age\prototypes\
• Roboport/accumulator/lightning defs are in .../entity/entities.lua.
• Cross-check field meaning at https://lua-api.factorio.com/latest/.

There is no Lua interpreter in this environment, so you can't run the mod. Keep changes small and idiomatic, and ask the author to test in-game before releasing.

7. Changelog & version bump

changelog.txt uses Factorio's strict format:

---------------------------------------------------------------------------------------------------
Version: 1.0.9
Date: 14. 06. 2026
  Features:
    - Some player-facing feature.
  Bugfixes:
    - Some fix.
  Info:
    - Infra / tooling note.
---------------------------------------------------------------------------------------------------

Rules:

• Separator lines are exactly 99 dashes. New versions go at the top.
• Category lines indent 2 spaces ( Features:); entries indent 4 spaces ( - ...). Common categories: Features, Bugfixes, Info.
• To bump a version, edit three files together: info.json (version), changelog.txt (new block at top), README.md (new "Version History" line).
• Prepend the changelog block programmatically (reuse the existing separator and the file's line endings) to avoid miscounting dashes and to preserve encoding.
• Player-facing buffs → Features; bug fixes → Bugfixes; CI/publishing → Info.

8. Release pipeline & Mod Portal publishing

Branch/PR flow

• Work on a branch off develop; open a PR into develop.
• Release by merging develop → main, which triggers release.yml.
• Don't merge to main until the author has tested in-game.

release.yml (push to main)

1. package.sh builds <mod>_<version>.zip.
2. Creates tag v<version> (tolerates re-runs if the tag already points at the current commit).
3. softprops/action-gh-release attaches the zip to a GitHub Release.
4. publish-factorio.sh uploads to the Mod Portal.

Mod Portal upload API (learned the hard way)

• Endpoint: POST https://mods.factorio.com/api/v2/mods/releases/init_upload.
• Auth = Authorization: Bearer <API_KEY> header + mod=<name> as multipart form-data. Do NOT put the key/mod in the URL query string.
• The response gives an upload_url; POST the file there with -F file=@<zip> (that pre-signed URL needs no auth header).
• The mod page must already exist on the portal — init_upload cannot create the first release. Publish the first version manually via the website.
• The API key comes from https://factorio.com/profile and must have the "Mod Portal: Upload Mods" usage/permission. A wrong-type or under-scoped key returns {"error":"InvalidApiKey"}.
• Trim whitespace from the secret before building the header (a trailing newline in a pasted GitHub secret corrupts the Bearer header). In Actions, also echo "::add-mask::$TOKEN" (guarded by $GITHUB_ACTIONS) to mask the trimmed value.
• Never print the token; keep curl -sS (no -v), no set -x.

develop.yml artifact gotcha

• actions/upload-artifact always re-zips its input. Uploading a pre-built .zip gives a zip-inside-a-zip on download. Instead, stage the mod folder under build/<mod>_<version>/ and upload path: build (the parent) — the artifact then contains the mod folder directly (one usable zip). .gitignore covers build/ and *.zip; both are excluded from the packaged mod.

9. Environment notes (this repo's setup)

• OS: Windows; shell: PowerShell (a POSIX bash is also available for scripts).
• gh CLI is installed at C:\Program Files\GitHub CLI\gh.exe (may not be on PATH).
• PowerShell here-strings mangle commit/PR bodies that contain parentheses or quotes. Write commit messages and PR bodies to a temp file and use git commit -F <file> / gh pr create --body-file <file>.
• bash -n script.sh for a quick shell syntax check; python is available for encoding/format validation. rsync/zip are NOT available in the local bash (they only run in CI on Linux).
• Commit convention: Conventional Commits (feat:, fix:, chore:, docs:), and end messages with a Co-Authored-By: trailer.

10. Quick checklist for a new buff

1. Read the real prototype in the game install; confirm fields.
2. Add a generic data.raw["<type>"] loop in the right FR block of data-updates.lua.
3. Reuse helpers; gate with player-creation if it should only hit buildable entities.
4. If shipping now: add a Features line to the current unreleased changelog version (or bump to a new version), and update README.md.
5. If it adds user-facing strings (it usually won't): update every locale/*/info.cfg.
6. Branch off develop → PR into develop. Let the author test, then develop → main.