API-Documentation?

  • January 2, 2018 at 04:01 #22594
    Marcus
    Participant

    Hello Apex-Team,

    i bought Apex Path, AI and Steering and i worked through all of the video tutorials, which are very well done and explain your examples quite well.

    What i´m missing is a complete API-Documentation of all your interfaces, classes and functionality so one could start easily implement custom versions of agents, which have Gesamtspeicher behaviors in terms of path-moving, animations and such.
    There are a few basic overwrites and custom implementations in your videos but it did not give me good high-level view over the possibilities as of yet.
    We really would need at least a List of Interfaces and what they do for units and grids.

    Your component design, as elegant as it works in unity, does not help in getting insights. For example the quickstarts do add a LOT of stuff to the scene (Gameworld) and to a Unit, so i have no idea what i really need of it and whats extra.

    I even found that your ComponentMasterComponent is HIDING other componenents of a unit. I did a wanderer quick-start, ticked off the wanderer-behavior and removed the component. The unit was still wandering. So i started removing classes to find out whats happening. Once i removed the MasterComponent, loads of hidden? classes were revealed, including another wanderer script.

    So as i understand the urge to keep the inspector clean, stuff like this is a nightmare to explore, when you wanna get a deeper understanding of whats going on and where to place my code to have full control over the behavior.

    I´m struggling with basic questions like:

    – Most important: Is there a Documentation or at least a topic-sorted list of classes/interfaces to work with
    – Whats actually calling the Move/Rotate/Stop methods when you have implemented the IMoveUnit Interface? I have stripped down a Unit which is not moving and still Move/Rotate get called each frame
    – how could a most stripped down Unit look like, which requests a Path(from, to) and gets an array of pathpoints back to move along…. only the absolut minimum of example and Apex-Components to start from?
    – How would a classdiagram of unit/gameworld comunication look like. how is the request/answer/processing flow?

    Same goes for Apex AI. A class/interface/API documentation would be needed

    January 2, 2018 at 14:00 #22598
    Geminior
    Keymaster

    We are aware that the written documentation is lacking, but unfortunately it is not viable for us to allocate the resources to improve it.

    You will find and API documentation included with the product in the examples and documentation folder.
    It is however quite sparse in that it mainly lists the various interfaces and classes but does not include many examples.

    The examples project does show examples of various use cases, most are backed by a video.

    The component master is simply an editor component that hides other components to keep the inspector clean. To remove a component, you need to actually remove it, unchecking it in the component master simply hides it.

    Most important: Is there a Documentation or at least a topic-sorted list of classes/interfaces to work with
    The API docs are the closest thing to what you seek.

    Whats actually calling the Move/Rotate/Stop methods when you have implemented the IMoveUnit Interface?
    It is used by the SteerableUnitComponent to perform the actual locomotion / rotation logic given a velocity.

    how could a most stripped down Unit look like, which requests a Path(from, to) and gets an array of pathpoints back to move along…. only the absolut minimum of example and Apex-Components to start from?
    The best starting point is simply using the Quickstart NavigatingUnit. It will add a number of components, of which a few are optional.
    The RigidBody is optional.
    The HumanoidSpeedComponent can be replaced by any SpeedComponent derivative.
    The DefaultHeightNavigator is only relevant if you need height navigation.
    The SteerToAlignWithVelocity is optional, although without it the unit will not rotate to face its direction of movement. It can be replaced by some other OrientationComponent to control unit orientation, the examples project has examples on this.
    Anything under the Debugging category is optional

    How would a classdiagram of unit/gameworld comunication look like. how is the request/answer/processing flow?
    I cannot provide you with a class diagram, but I can briefly explain.
    The game world components are singleton services that provide the functionality needed to navigate.
    The unit components are specific to the unit and operate on the unit alone. Unit components will interact with the game world components in various ways, e.g. requesting a path.

    In short, the request processing flow is as follows:
    1. When a request is made, the path service queues it for processing.
    2. The path service processes the request once any other requests before it have been processed.
    3. The path service calls back to the requester and delivers the result.
    4. The requester analyses and applies the result.

    I hope this proves sufficiently helpful.

    January 4, 2018 at 01:29 #22600
    Marcus
    Participant

    Hello Support-Team,

    thanks for your reply. I must say it´s a bit disappointing to read that we can´t have a full API-Documentation any time soon. From pricetag to featurelist Apex Path looks like a professional Pathfinding API, not “only” a bunch of very good default behaviors ready to use… and it might still be as good as i need it to be, but a professional tool needs a better documentation and guide users beyond “just” using Quickstarts and override/customize some of the behaviors.

    As soon as you intend doing something beyond the tutorials it´s pretty clear that we miss some better understanding what Apex is doing and how the information gets processed from the grid through the Steering-Pipeline and so on into the final movement.

    Anyway i keep asking some questions in this thread if they come up while exploring the API:

    1) API-Docs: The Docs in the examplesfolder are pretty helpful indeed. thanks for pointing me there

    2) ComponentMaster: So one could just remove it to see the whole cascade of components without removing other important parts/links? From what i´ve tested that seems to work. If so, thats a really important information which should be covered somewhere (maybe i missed it)

    3) Most stripped down unit: I followed your instructions, removed the ComponentMaster so see whats been added. There are way more components added then you covered.

    – HumanoidSpeedComponent: So this is providing the speed values to a moving target, got that. So does this mean every agent need this or a derived class from SpeedComponent or a class that implements IDefineSpeed? What happens if i have more then one? Whats the right usage, like make sure only one component implements either class or interface?

    – i was also able to remove the SteeringScanner and the seperation and Avoidance steerings, which did depend on it. So it seems that some more advanced steerings need an implementation of a ScannerClass to work. Could you explain how those work and how one could hook in to customize/implement our own steering behaviors or get information out of these to feed into other parts of the game.

    – SteerableUnit seems to gather all other SteeringComponent Derivatives and combines them to simply velocities which get passed to the movement-part. Confusingly it´s also implementing IMoveUnits classes. I was wondering a lot why the unit was moving at all when no custom IMoveUnits was attached. So by default this is the only class which moves units? When i implement my own IMoveUnits class, those (and all possible other default ones) get ignored and only mine get used?

    – SteeringComponents: So all steering Components work with an Steering input and some code to alter it to a steering output right? There contribution to the final outcome (processed in the SteerabeUnit) is priority and weightbased? Is that pretty much it? So i could do as much steering as i want and i would have to balance it via those two values?
    Also this one seems to be outdated, since it implements the wrong method, right? https://www.youtube.com/watch?v=rJUNmcq0C9s

    – ArrivalBase: Seems to be one specifc versions of steering-processing. Are there others? What do i need to take care of, when writing custom ArrivalBase-Classes?

    – UnitComponent and UnitFascade: So what UnitComponent actually does is not clear for me. It´s mandatory and it privides stuff like IUnitAttributes and some other things what your system depends on. Then it also provides stuff like isSelected which seems to control the selection and visuals. Isn´t that a bit misplaced cause it´s bound to some of your example implementations, not a basic property ALL agents might need?

    – It also has a FieldOfView property. It seems that i can use this for custom scanner to only “see” units in field of view. Is there an example or can you explain me how i could use this property for fieldOfView depended unit detection?

    – Could i simply derive from UnitComponent to implement other game-specific properties used in path finding or ApexAI?

    – SteerForPathComponent: Seems to be the point where the path comes into steering. There is a full implementation of pathprocessing. So if i would want for some custom functionallity how could i extend that class or rewrite it?
    -> From the top of my head i would think of something like a cover system, where a unit would be allowed to get closer to a obstacle then allowed by the path. i could also imagine a solution to this where i just move to the closest walkable point to the cover and then disable/override ApexPath for the last steps into the blocked grid.

    – Locomotion and Movement: In the Locomotion tutorial you show how to reimplement the default behavior (no rigidBody or CharacterController) from the SteerableUnitComponent, right? Also all defalut implementations use the same interface, so the same 3 methods. If one would need more properties of the character to do locomotion and animations to just implement that interface on an animationcontroller class which has all needed props and just controlls the animations, while another implementation controlls the translates and rotations?

    Thanks in advance and don´t hesitate to link me to allready answered questions if some of mine got allready covered

    January 4, 2018 at 01:36 #22602
    Marcus
    Participant

    4) Information flow: I´d need some insights into and beyond your point “4. The requester analyses and applies the result.”.

    From what i´ve got so far the path arrives at “SteerForPath”
    -> then maybe filters and takes in account stuff from UnitComponent
    -> then it triggers SteerableUnit which then evaluates all SteerableComponents for their final velocities.
    – > Then looks for a IMoveUnits implementation or choose the default ones

    A full breakdown of the information/decision flow just in terms of Interfaces and classes would be great.

    January 4, 2018 at 15:13 #22605
    Geminior
    Keymaster

    I can only say that we are disappointed as well, but unfortunately the asset store has proven a money sink, which is why we no longer allocate time to improve / expand the products.
    A low cost, low volume market, as the asset store has proven to be, is simply not a viable business.

    With that said, let me address your concrete questions.

    @2: yes, the ComponentMaster is an optional editor only component with no functional impact.

    @3: I only mentioned the optional / replacable components from Apex Path. It is true there are additional components added when Apex Steer is detected.
    Additionally there are components I did not mention since they are required.

    – Only one SpeedComponent / IDefineSpeed implementation is supported, however the implementation can be as complex as you like.

    – The SteeringScanner is used by components that need knowledge about other units close to it. The built-in components using it are the SteerForUnitAvoidance and SteerForSeparation components.
    You are free to use it for other components, simply get a reference to it and access the units property. Have a look at the SteerForSeparation to see an example.

    – SteerableUnit defines three IMoveUnits implementations which are used (only one of them is used) if no custom implementation is found.
    And yes, SteerableUnit collects the steering from Steering components on the unit in priority order using the first to provide output (multiple components can have the same priority in which case their output is accumulated).

    The linked video is indeed outdated, the signature is not the same. This video however is an updated version.

    – ArrivalBase is a derivative of the SteeringComponent that adds a few Arrive methods to complement the Seek methods.
    Arrive will slow the unit down as it approaches its destination, while Seek will just go full throttle until the destination is reached, which may cause overshooting.
    You can find usage examples in both the main project as well as the examples project.

    – The UnitComponent supplies some required information and has some optional stuff on it as well.
    There is no requirement to use the selection logic, and while we probably could have put it elsewhere, it has never been a priority as it has no overhead.

    – FieldOfView, have a look at its usage in SteerForUnitAvoidanceComponent.

    – The UnitComponent has a custom editor and is also used explicitly in QuickStarts. So without making modifications to the code, then no, otherwise yes.

    – SteerForPathComponent handles steering along a path, that is it.
    If you need more advanced functionality I would either create an entirely new implementation inspired by SteerForPathComponent or have a higher priority component that only provides output in certain circumstances, e.g. moveing to cover.

    – You can only have one IMoveUnits implemenation active. That implemenation can be however complex you like it to be.
    Also remember you have full source code. You can modify the default functionality in any way you like to fit your needs.
    So you could add more state to the SteeringInput if you need it.

    @4: Path finding and steering are two separate flows. Path finding is only used by the actual locomotion providing components, e.g. SteerForPath and that is where the path finding flow ends.
    Once the path result has been delivered the flow starts over with the next request.

    I already covered most of the steering flow in the answers above.
    SteerableUnit is not triggered, it requests steering from relevant steering components each fixed tick.
    The IMoveUnits implementation is used internally by SteerableUnit to do the actual movement / rotation, by e.g. moving the transform, setting an animation parameter or whatever.
    It is retrieved/instantiated as start-up, not dynamically each frame. In other words, replacing the IMoveUnits implementation at run time is not supported.
    Again you are of course free to remove that limitation.

You must be logged in to reply to this topic.