Portal, mirror and file formats #
How the app talks to the mod portal and the mirror, what it parses, and the local file formats it reads and writes. Portal and mirror requests are anonymous and limited to mods.factorio.com, assets-mod.factorio.com, mods-storage.re146.dev, and the re146.dev/factorio/mods/modinfo endpoint. Description images may also be fetched over HTTPS without cookies or credentials. Counts below come from sampled responses.
Endpoints #
| Endpoint | Contract |
|---|---|
GET /api/mods?page_size=max |
Bulk catalogue (about 14 MB, roughly 24k entries). Has name, title, owner, summary, downloads_count, category, score, latest_release; no tags, images or release list. Cached six hours. |
GET /api/mods?page_size=max&version=2.0 |
Catalogue filtered by game line. Release compatibility is still validated locally. |
GET /api/mods?page_size=max&namelist=a&namelist=b |
Named mods with full releases and pagination: null; latest_release may be missing and a release's info_json may carry only factorio_version. Drives Updates. |
GET /api/mods/<name>/full |
Adds changelog, timestamps, Markdown description, homepage and source, images, license, tags, thumbnail and every release with dependency strings. Cached 24 hours; installed mods keep a durable copy by name and version. |
GET /search?... |
Non-blank query returns HTML, 20 results per page, with counts, facets and pagination. A blank /search returns an introduction page, not a list. |
GET /browse/downloaded, /browse/updated, /browse/trending |
Paginated blank-query results. Blank Relevance and Downloads map to Downloaded, Recently updated to Updated, Trending to Trending. |
GET /api/mods ignores q. POST /api/search needs a username and token and isn't used. /api/v2/mods returns 404. /highlights is an editorial page without the search contract and isn't used for blank Relevance.
Search parameters: query, factorio_version (the site canonicalises version), sort_attribute (relevancy, most_downloads, last_updated_at, trending), page, and repeated category / exclude_category, tag / exclude_tag, expansion / exclude_expansion. Facet IDs such as utilities, internal, trains, space-age are the values.
HTML parsing #
crates/core/src/portal_search.rs, tested against the saved pages in crates/core/tests/fixtures/:
- Facets are
div#facet-control-<expansion|category|tag>-<id>with a numeric.badge, include and exclude inputs and checked state. - Result cards sit under
div.mod-list. Title and internal name link to/mod/<name>?from=search, the owner to/user/<owner>. The summary isp.result-field.pre-line.line-clamp-4; its closingpmay be omitted and title or summary may contain highlightemtags. HTML entities such as'are decoded. - Thumbnails are under
.mod-thumbnail. Category labels and.mod-tagsgive readable tag names. Exact update and download values are intitleattributes. The card's supported Factorio range is not the mod's release version. - The found count and pagination links tell a valid empty
mod-list(zero results) from the introduction page. Pagination and tab links keep the game line and filters. - The checked filters in the response are compared with the request. The site may add an Internal exclusion on Updated; any mismatch or changed markup triggers the catalogue fallback with a notice.
Fallback results come from the local catalogue, and full details supply tags and images separately; the bulk catalogue never contains those.
Releases, images and downloads #
A release has version, released_at, file_name, download_url, sha1, info_json.factorio_version, and sometimes file_size and dependencies. A release is installable only when its game line equals the installed major.minor, even if the site's latest release targets another line (a mod can list 3.4.2 for 2.1 and 3.3.8 for 2.0; the full namelist arrays keep both).
Thumbnail paths like /assets/<sha1>.thumb.png resolve on https://assets-mod.factorio.com; /assets/.thumb.png is the placeholder. Image responses may be PNG, JPEG or GIF; the extension is detected from the bytes. Images on other hosts become readable links and are never fetched.
The re146.dev mirror serves https://mods-storage.re146.dev/<name>/<version>.zip and proxies /full at modinfo?id=<name> (the app asks the portal directly). The server supports HEAD, Content-Length and byte ranges on sampled files. New releases may be missing for a while, so a 404 gives a clear message and a link to the portal. Official download URLs need a login and are not used. Links opened in the browser are validated HTTP(S) URLs, separate from the fetch allow-list.
Local formats #
mod-list.json:{ "mods": [{ "name": "example", "enabled": true, "version": "1.2.3" }] }.versionis optional; "Latest" removes it.mod_list.rskeeps the game's blank-line layout and the first-write.bak.- Mods are unversioned or versioned folders, or
name_version.ziparchives with one enclosing directory holdinginfo.json. The game reads zips directly. Builtins live under the install'sdata/. info.json: name, version, title, author, optional contact, homepage and description, Factorio line, dependencies. The identity and archive integrity must match the downloaded release before it replaces anything.- Dependency strings start with an optional prefix (none for required,
?optional,(?)hidden optional,!incompatible,~required without load-order effect) followed by the name and an optional comparison (=,<,<=,>,>=) and version.version.rsparses them. - Locale:
locale/en/*.cfgentries under[mod-name]and[mod-description]override titles and descriptions for builtin, folder and zip mods. The parser handles sections, first-=splitting, BOM, CRLF, comments and escaped newlines; later files in sorted order win. Only English is read. mod-settings.datis binary property-tree data and is never touched.
Descriptions and images #
Descriptions are the portal's Markdown, parsed by crates/core/src/markdown.rs and text.rs and shown through Slint's StyledText. There is no length cap; long descriptions scroll. Formatted block models for the last 16 documents are cached so thumbnail updates don't rebuild them.
- Blocks: headings h1 to h3 (including no-space headings), paragraphs, nested and ordered lists, code (fenced and indented), rules and images. Pipe tables stay readable text. Leading
>markers stay as text; there is no quote block. - Inline: strong, emphasis, nesting, strikethrough, inline code, links and hard breaks. Active emphasis is closed and reopened at hard breaks, whitespace inside paired delimiters moves outside, escaped punctuation and code spans stay opaque, and a closing backtick run must match the opening run. A link label with mixed formatting becomes separately linked segments so every styled word stays clickable. Inline
<b> <strong> <i> <em> <del> <s> <strike> <code>and any-case<br>normalise to the same syntax. Reference links, arbitrary HTML and malformed delimiters fall back to readable text. - Images: thumbnails and description images share the image queue (four requests in flight). Only the shown description queues images; switching mods drops unstarted requests. Consecutive images in one paragraph flow left to right at natural size with 4 px gaps, wrapping or shrinking to the pane width without enlargement. Loading placeholders are 28 px high with dim alt text. Failures/refusals become blue alt-text links, keeping the outer link for badges. Plain loaded images open the current frame in the lightbox; linked images open their outer URL. External fetching is HTTPS DNS only, at most three validated redirects and 15 s per image, no download size cap; decode limits apply (see decisions). External images persist in disposable description-images/ until Clear cache; portal-host images retain portal-thumbs/. GIF, animated WebP and APNG animate with disposal/compositing and bounded frame storage. Timers pause offscreen, under other tabs/changelogs and while minimized, resuming the same playhead. Gallery images still load when opened. Browser launches use the system opener; tests inject a recorder.
- Details pane: title and browser action, metadata beside the retained thumbnail, a horizontal gallery, then the formatted description. The website's latest-release metadata is shown separately from the compatible release used for actions. Slint's styled text has no line-height control, so spacing differs from the website.
- Gallery: the horizontal scrollbar supports thumb and track dragging; dragging tiles or padding doesn't scroll the parent vertically. If the gallery fits, wheel input goes to the details pane; if it overflows, horizontal wheel scrolls the gallery.
- Lightbox: opens fitted with 20 px margins and never enlarges past natural size. Wheel zoom is anchored at the pointer and clamped from fit to 8x, drag pans within bounds, double-click toggles fit and 100%. Clicking the image keeps it open; X, the backdrop and Escape close it and return keyboard focus. Software captures rasterise the visible viewport with premultiplied bilinear filtering so zoomed images have no transparent fringes.
Tests cover the parsing with real captured descriptions (crates/app/tests/fixtures/alien-biomes-planet-controls.md exercises padded emphasis such as **Temperature: HotClimates: **) and inspect the produced styled-text spans and link ranges.