Skip to content

Core: Add Framework for jsonworld loading - #6347

Draft
qwint wants to merge 15 commits into
ArchipelagoMW:mainfrom
qwint:jsonworld
Draft

Core: Add Framework for jsonworld loading#6347
qwint wants to merge 15 commits into
ArchipelagoMW:mainfrom
qwint:jsonworld

Conversation

@qwint

@qwint qwint commented Jul 20, 2026

Copy link
Copy Markdown
Collaborator

What is this fixing or adding?

Adds a jsonworld abstract world class and helper functions to define expected formats
adds a doc to describe these formats and tests to ensure they are working as expected

Note: I fully expect more formats to be defined for different usecases, but I don't believe itemizing all of those is a blocker for this pr

What is a blocker for this pr is defining how the worlds get loaded and their final format, some suggestions I've thought about and had in discussions are:

  • raw world_name.json files with no metadata and either live in custom_worlds or a new folder. probably the easiest but the least useful
  • a specific world_name.apworld format defined as a new type of APWorldContainer with specific manifest values and no init. would be the cleanest, but I don't know how easy it would be to guarenteed safely load (i.e. if someone did package with python code is it then no longer a safe file to load)
  • a new container with a specific extension like world_name.apjsonworld that would act similar to the apworld suggestion but be loaded in a different process that would not try to import them at all
  • (horrible) (don't pick this) or we could technically support the jsonworld data packed into the manifest itself

an additional note is the current code has no webworld definition, there is a reasonable argument that there should be one defined and the appropriate .md files should be ingested and served if webhost is to support these worlds, but that does add complexity to the format (or at least limits us to a APWorldContainer-like that can include extra files)

How was this tested?

converted my air delivery implementation into a jsonworld file https://github.com/qwint/Archipelago/blob/da2ba4dfa261546b79554fc4223655b7c745ca81/custom_worlds/air_delivery.json
and loaded it directly with

from .json_world import JsonWorld
with open(user_folder + "/air_delivery.json") as f: air_delivery = json.load(f)
JsonWorld.from_json(air_delivery)

If this makes graphical changes, please attach screenshots.

@qwint
qwint marked this pull request as draft July 20, 2026 00:57
@github-actions github-actions Bot added affects: core Issues/PRs that touch core and may need additional validation. waiting-on: peer-review Issue/PR has not been reviewed by enough people yet. and removed waiting-on: peer-review Issue/PR has not been reviewed by enough people yet. labels Jul 20, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

affects: core Issues/PRs that touch core and may need additional validation.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant