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 22 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 from the origin region, checking entrances one by one and adding newly reached nodes (regions) and their entrances to the queue until there is nothing more to check.
qwint marked this conversation as resolved.
Show resolved Hide resolved

For performance reasons, AP only checks every entrance once. However, if any entrance's access_rule depends on region access, then it is possible for this to happen:
1. An entrance that depends on a region is checked and determined to be nontraversable because the region hasn't been reached yet during the graph search.
2. After that, the region is reached by the graph search.
qwint marked this conversation as resolved.
Show resolved Hide resolved

The entrance *would* now be determined to be traversable if it were rechecked, but it is not.
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 almost all of the performance upsides. Even a game making heavy use of indirect conditions (See: The Witness) is still significantly faster than if it just blanket "rechecked all entrances until nothing new is found".
qwint marked this conversation as resolved.
Show resolved Hide resolved
The reason entrance access rules using `location.can_reach` and `entrance.can_reach` are also affected is simple: They call `region.can_reach` on their respective parent/source region.
qwint marked this conversation as resolved.
Show resolved Hide resolved

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 also possible for a world to opt out of indirect conditions entirely, although it does come at a flat performance cost.
qwint marked this conversation as resolved.
Show resolved Hide resolved
It should only be used by games that *really* need it. For most games, it should be reasonable to know all entrance → region dependencies, and in this case, indirect conditions are still preferred because they are faster.
qwint marked this conversation as resolved.
Show resolved Hide resolved