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: Dev FAQ - About indirect conditions #3698

Closed
wants to merge 19 commits into from
Closed
Changes from all commits
Commits
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 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.

For performance reasons, AP only checks every entrance once. However, if entrance access conditions depend on regions, then it is possible for this to happen:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

rewriting the suggestion because it technically had a conflict lol

Suggested change
For performance reasons, AP only checks every entrance once. However, if entrance access conditions depend on regions, then it is possible for this to happen:
For performance reasons, AP only checks every entrance once. However, if an entrance's access condition depends on regions, then it is possible for this to happen:
Suggested change
For performance reasons, AP only checks every entrance once. However, if entrance access conditions depend on regions, then it is possible for this to happen:
For performance reasons, AP only checks every entrance once. However, if any entrance access condition depends on regions, then it is possible for this to happen:
Suggested change
For performance reasons, AP only checks every entrance once. However, if entrance access conditions depend on regions, then it is possible for this to happen:
For performance reasons, AP only checks every entrance once. However, if entrance Access Conditions depend on regions, then it is possible for this to happen:
Suggested change
For performance reasons, AP only checks every entrance once. However, if entrance access conditions depend on regions, then it is possible for this to happen:
For performance reasons, AP only checks every entrance once. However, if entrance access_conditions depend on regions, then it is possible for this to happen:

giving a couple more options too, because I don't think there's one way to fix this, but as-is it reads strange without the assumption that "access condition" is one idea and not multiple words you have to parse their role in the sentence
easiest is probably to rewrite the whole sentence, but i think any of these help 😅

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.

The entrance *would* now be determined to be traversable if it were rechecked, but it is not.
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.
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".
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.

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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It seems weird to me to call this opting out instead of opting into having your regions always rechecked

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this is probably more intuitive? Idk. Willing to consider a suggestion but I think rn I'd keep it

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.