Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docs: add description of Indirect Condition problem #4295

Merged
merged 27 commits into from
Dec 12, 2024
Merged
Changes from 25 commits
Commits
Show all changes
27 commits
Select commit Hold shift + click to select a range
db5be6a
Docs: Dev FAQ - About indirect conditions
NewSoupVi Jul 27, 2024
295e719
Actually copy in the text
NewSoupVi Jul 31, 2024
f9b07a5
Update docs/apworld_dev_faq.md
NewSoupVi Jul 31, 2024
8420c72
Update docs/apworld_dev_faq.md
NewSoupVi Jul 31, 2024
205fa71
Update docs/apworld_dev_faq.md
NewSoupVi Jul 31, 2024
3a70bf9
Update docs/apworld_dev_faq.md
NewSoupVi Jul 31, 2024
850033b
Update docs/apworld_dev_faq.md
NewSoupVi Jul 31, 2024
e74e472
Update docs/apworld_dev_faq.md
NewSoupVi Aug 13, 2024
9ec1f8d
Update docs/apworld_dev_faq.md
NewSoupVi Aug 13, 2024
49394be
Update docs/apworld_dev_faq.md
NewSoupVi Sep 5, 2024
1d8d04e
Update docs/apworld_dev_faq.md
NewSoupVi Sep 5, 2024
cf3d4ff
Update apworld_dev_faq.md
NewSoupVi Sep 5, 2024
663b5a2
Update docs/apworld_dev_faq.md
NewSoupVi Sep 5, 2024
a1779c1
Update apworld_dev_faq.md
NewSoupVi Sep 5, 2024
8cefe85
Update docs/apworld_dev_faq.md
NewSoupVi Sep 5, 2024
df1f3dc
Update docs/apworld_dev_faq.md
NewSoupVi Sep 5, 2024
153f454
Update docs/apworld_dev_faq.md
NewSoupVi Sep 5, 2024
ce8d254
Update apworld_dev_faq.md
NewSoupVi Sep 5, 2024
a2ba2f3
Update docs/apworld_dev_faq.md
NewSoupVi Sep 5, 2024
b350521
Update docs/apworld_dev_faq.md
NewSoupVi Sep 5, 2024
5a09296
fix the last couple of wording issues I have with the indirect condit…
qwint Nov 30, 2024
c90ddf8
I didn't like that wording
qwint Nov 30, 2024
2da8ce8
Apply suggestions from code review
qwint Dec 5, 2024
8296621
Apply suggestions from code review
qwint Dec 5, 2024
7f61f87
Update docs/apworld_dev_faq.md
qwint Dec 6, 2024
a9e9c58
Update docs/apworld_dev_faq.md
qwint Dec 6, 2024
b151794
Update docs/apworld_dev_faq.md
qwint Dec 6, 2024
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 23 additions & 0 deletions docs/apworld_dev_faq.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,3 +43,26 @@ A faster alternative to the `for` loop would be to use a [list comprehension](ht
```py
item_pool += [self.create_filler() for _ in range(total_locations - len(item_pool))]
```

---

### I learned about indirect conditions in the world API document, but I want to know more. What are they and why are they necessary?

The world API document mentions how to use `multiworld.register_indirect_condition` to register indirect conditions and **when** you should use them, but not *how* they work and *why* they are necessary. This is because the explanation is quite complicated.

Region sweep (the algorithm that determines which regions are reachable) is a Breadth-First Search of the region graph. It starts from the origin region, checks entrances one by one, and adds newly reached regions and their entrances to the queue until there is nothing more to check.

For performance reasons, AP only checks every entrance once. However, if an entrance's access_rule depends on region access, then the following may happen:
1. The entrance is checked and determined to be nontraversable because the region in its access_rule hasn't been reached yet during the graph search.
2. Then, the region in its access_rule is determined to be reachable.

This entrance *would* be called reachable if it were rechecked, but it won't be rechecked this cycle.
qwint marked this conversation as resolved.
Show resolved Hide resolved
To account for this case, AP would have to recheck all entrances every time a new region is reached until no new regions are reached.

However, there is a way to **manually** define that a *specific* entrance needs to be rechecked during region sweep if a *specific* region is reached during it. This is what an indirect condition is.
qwint marked this conversation as resolved.
Show resolved Hide resolved
This keeps most of the performance upsides. Even in a game making heavy use of indirect conditions (ex: The Witness), using them is significantly faster than just "rechecking each entrance until nothing new is found".
The reason entrance access rules using `location.can_reach` and `entrance.can_reach` are also affected is because they call `region.can_reach` on their respective parent/source region.

We recognize it can feel like a trap since it will not alert you when you are missing an indirect condition, and that some games have very complex access rules.
As of [PR #3682 (Core: Region handling customization)](https://github.com/ArchipelagoMW/Archipelago/pull/3682) being merged, it is possible for a world to opt out of indirect conditions entirely, instead using the system of checking each entrance whenever a region has been reached, although this does come with a performance cost.
Opting out of using indirect conditions should only be used by games that *really* need it. For most games, it should be reasonable to know all entrance → region dependencies, making indirect conditions preferred because they are much faster.
Loading