WebWalker support for Player-owned-house teleportation functionality.

[Krulvis]

In short, it would be beneficial to the web walker to support Player-owned-house teleports. PoH teleporation is a game-changer and supporting in the web would open a world of possibilities.

As soon as I found Microbot, I started development on this. I asked around and got help from some people pointing me in the right direction. When I had a working MVP, I created a PR and was curious to hear people's thoughts.
The PR
This quickly let to some discussion on how a feature like this should be implemented without any clear answers. As such, I feel like it is useful to open this discussion in a different format to see if we can all pitch in designing the best approach for this.

My vision of the goals for this feature:

• Toggle that lets the user determine if they want to use available PoH teleports in Web Walker plugin
• PoH teleportation features (JewelleryBox, Mounted Glory, Portals) are stored and accessible by the web.
• The web has all of the existing PoH teleportation methods added as transports to be considered in pathfinding
• Getting to PoH is handled by regular TELEPORTATION_SPELL, TELEPORTATION_ITEM, TELEPORTATION_PORTAL Transports.
• When the pathfinder is ran, it checks whether getting to the PoH is feasible and which teleports are available there
• The walker executing the best path found is able to handle PoH teleportations

Some requirements for PoH in the pathfinder:

• Even with caching, the user will have to visit their PoH at least once to let the cache determine available teleports.
• Most teleportation functionality can be determined based on GameObjects/TileObjects preset in the PoH. The Nexus Portal can be determined through varbits.
• Some GameObjects (portal) have multiple variants (ids) that all link to the same teleportation (spell-like)
• Some GameObjects (JewelleryBox) have a list of jewellery-like teleports that are all made available
• The PoH is complex in the sense that it is instanced and most of all, cut-and-pasted from the map. This means that every room-type in combination with house styling is represented on the worldmap once and according to your PoH layout they are taken from the map and pasted together in your PoH instance. This means that when you move in your PoH from room to room you seemingly teleport across the world map.
• Because of this cut-and-pasting, the pathfinder and walker as is don't work in the PoH and pathing is impossible inside the PoH

My approach to data is as follows:
The pathfinder's data is stored in TSVs and parsed when the shortestpath plugin is started. This felt like an old-school approach to me and since all the data is already available through Runelite, the only thing I had to do was map functionality to destinations. You can see the result of that here for Mounted Glory. This follows an enum structure where the class determines the type of teleportation and the values represent the possible destinations. I got some backlash on this from @g-mason0 since he claimed that consistency was key for the pathfinder. To meet him half-way I have implemented a converted that transforms the enum to TSV on runtime and which is parsed like any other Transport in the pathfinder.

My approach to caching:
I built an Rs2PohCache that is able to keep track and register new teleportation systems available in a player's PoH. What it essentially does is map the available destinations to the transportation system that enables this teleportation. The Rs2PoHCache also supplies a method that allows the pathfinder to link the Transport to a teleportation functionality.

My approach to handling PoH tranportation:
I have created a new TransportType value 'POH' and implemented that throughout the pathfinder and walking code. It is implemented like any other transport system with the necessary if transport.getType() == TransportType.POH yadayda. Since the pathfinder can't path within the PoH, I have designed the POH transport to be a simple interaction with gameobjects/widgets inside POH. When handling said interactions failes and you end up inside POH it will find a new path with the same PoH transport step included and continue where it left of. The only way it can potentially break is if the caching is wrong and the found PoH transport is in reality not available. For the actual handling of the transport I went a little bit of different route. Since the pathfinder, shortestpath and rs2walker code is quite large, I felt like it was best to implement the actual gameobject interaction outside of this class. The pathfinder finds the available POH transport by checking whats in Rs2PohCache -> Rs2Walker recognizes the Transport step as a TranportType.POH and teleports to PoH and lets the teleportation functionality obtained from Rs2PohCache do the rest. The actual teleportation (finding and interacting with GameObject and Interface) itself is done by its associated PoH API implementation. See PohPortal for example.
This allows us to also have the Teleportation within PoH made available in the PoH and lets any plugin use it as it wishes. In addition to that, it allows us to serve a single TSV file with all the teleports that are possible in PoH.

My approach to the PoH instance/mapping problem:
I went for the simplest route possible: don't even try to walk inside the PoH. The only thing that is done in PoH is interacting with the teleportation object. This means that there is the least amount of effort required on the pathfinder/walker with the added limitation of PoH with closed doors not being supported.

This discussion is not a way for me to claim that I know what is best but a way to lay out all the required steps that I've gone through and the insights I've gained as well as the difficulties and limitations with implementing them into the pathfinder as it currently stands. I invite you all to think critically and raise any concerns you see. If you feel like there are missing features, lets try to see how we can get them added. If you have a different approach that you feel is more reasonable, please do share.

[Voxsylvae]

Thanks for opening this discussion.
I should mention that I've been working on PoH integration for some time and have a different architectural approach. Working on this feature led me to develop the caching system as a result of the integration needs.
My implementation includes:

• Rs2walker API integration, support for optional features ( like walkTo(Point).useTeleports().usePOH() style)
• Optimal route planning that considers all available transport options: current inventory, banked teleport items, and PoH teleports
• All features are completely optional - users can choose raw walking, walking with banked teleports, PoH integration, or any combination
• Support for house advertisements for PoH teleports when your own house isn't optimal

You were also by informed @g-mason0 that I was working on this and didn't reach out to me. I tried to coordinate with you to avoid duplicate efforts, but it seems we ended up with parallel implementations anyway. I explained my caching-based approach to you during our discussions. Which lets you implement the caching based approach instead of the plugin based approach
The maintainers will ultimately decide the direction. I'm willing to abandon my implementation if that's what's decided, but I wanted to make sure it's known that I've been working on this for quite some time and have put significant effort into it. You also was informed, that I'm working on in and not reached out to me.

[Krulvis]

Im sad to see you're taking the work I've done as a personal attack on you. I'll try to rephrase what you're focused on into features that are currently non existent in the approach that I am proposing.

• supporting house advertisement scanning to enable support for the web walker to enter other people's poh and using their teleport methods.
• considering bank items to determine if it is faster to go to bank -> take poh teleports -> make use of poh / house advertisement transports.
• Rs2walker builder api with features such as: walkTo(Point).useTeleports().usePOH().

I think these are all great suggestions that could be really beneficial to the community and I dont see a reason to avoid them. I dont, however, understand why this has to be a requirement for POH support and can see them being very powerful and complex PR's by themselves. What -in your opinion- is the advantage of including all of that in the same pull-request as PoH support?

[Voxsylvae]

Summarizing my approach:

My implementation offers these architectural features:

Pathfinder Integration:

• Directly utilizes existing Transport.java infrastructure and available .tsv file system - no new transportation types or .tsv files introduced
  -> the information is already in the current .tsv files and transport system included
• Maintains consistency with current pathfinder design and established Microbot code patterns
• Interaction with teleport objects handled through utility classes per PoH room rather than new transport types
• All utility classes can be utilized within scripts, providing flexibility for plugin and script writers

Caching & Automation:

• Event-driven automatic updates via RuneLite's EventBus system - no manual updates required
• Caches complete house data (varbits, Rs2GameObjectModel) not just teleports
• Supports both self-owned and advertisement houses in unified cache
• Utilizes Rs2ObjectsCache and Rs2VarbitCache infrastructure directly within Rs2PohCache

Features:

• API integrated within Rs2Walker, supporting optional PoH feature usage (walkTo(Point).useTeleports().usePOH() style)
• Optimal route planning considering ALL transport options: current inventory, banked teleport items, and PoH teleports
• All features completely optional - users can choose any combination
• Support for house advertisements when your own house isn't optimal
• PoH utility classes for navigation and interaction beyond just teleports

Future Extensibility:
My approach enables simple future additions like PoH prayer altar, spellbook swap, rejuvenation pool, and other room utilities outside the scope of transportation, while maintaining architectural consistency with the Microbot infrastructure.

[Krulvis]

Ah that's a great overview. Thanks! Many of these sound like great additions. I think its really good to create a more grand overview of all the possibilities that can be added. You're talking about the 'future extensibility' which is fantastic. I'm wondering, however, why more of the features you're proposing in the initial implementation aren't in the future extensibility list? It would make your PR smaller, more comprehensible, easier to review and most of all faster to get merged. I'll try to go over each point individually to split the discussion up a bit so we're not constantly talking about everything at the same time. Anything that I don't mention is what I believe we share in design strategy and doesn't differ between our implementations.

- Caching strategy, which you seem to make much broader compared to what I've proposed.
Can you explain why making this so elaborate is necessary or what the advantages are?

- Directly utilizing existing .tsv transport files without creating a PoH specific tsv file
What are the advantages of this? It sounds to me like it only makes things more complex since you now have to juggle for each existing transport whether that is a transport that could be handled by PoH.

- Supports both self-owned and advertisement houses in unified cache
I like the idea but I doubt this is necessary for a first PoH WebWalker implementation. We should definitely make sure that everything that would be required for it can be added at a later stage without breaking changes.

- Utilizes Rs2ObjectsCache and Rs2VarbitCache infrastructure directly within Rs2PohCache
Nice, I dont use objects at all but making use of Rs2VarbitCache sounds like a definite improvement over what I have

- API integrated within Rs2Walker, supporting optional PoH feature usage (walkTo(Point).useTeleports().usePOH() style)
As far as I understand it, this is creating a 'builder' for the Walking api? If I interpreted that correct I think it should be a separate PR altogether and shouldn't interfere directly with PoH.

- Optimal route planning considering ALL transport options: current inventory, banked teleport items, and PoH teleports
We've already established that everything should be added in the pathfinder and rs2walker through the standards that exists. How pathfinder handles inventory vs. banked items or any kind of teleport transportations is not unique for PoH and I don't understand what this has to do with the PoH feature requirements.