Difference between revisions of "OgreNavLib"

Latest revision as of 15:56, 14 November 2017

OgreNavLib

What is OgreNavLib?

OgreNavLib is a library of commands I have written, so scripts can navigate the world. This is a complete rewrite of 'OgreNavLib.inc', which will be phased out and not updated.

This will primarily be used by advanced scripters, such as myself, BJCasey, Pork, etc, to automate navigating. While technically anyone is welcome to use it, it will require a solid understanding of LavishScript to use.

What's new over the old one?

It was completely re-written from the ground up. The movement is better, the error reporting is better, the code is better, and debugging it is 100 times better.

Oh, did I mention, it supports flying?

How to use it? - Without creating a script

For basic use, it will be nearly identical to the old way. You create a map: (this command may change): ogre navmap

While you're creating your map, you can fly as you see fit, land when you want, and fly again.

Note: Technically creating a map is not required, as with before, if there is direct line of sight with no obstacles, it will go directly there, including flying to/from a location.

When you want to move some where, you do the same as what you have done previously:

You navigate to it. (This command will likely change): ogre navtest <parameters>

• Note: ogre navtest is identical to ogre nav, except it uses the new lib instead of the old one. But all flags will. Such as -loc, -ntr, -tr, etc etc.

For example:

• ogre navtest Point1
  • You would navigate to a custom named point of 'Point1'
• ogre navtest -loc 10 30 -382
  • You would navigate to a location of: 10,30,-382

How to use it? - With creating a script - Basic example

This will give you more control over how the lib works, but for obvious reasons, is way more technical.

Create a script, and include the library, then create the library, change any values in the library you wish to change, then have start the navigation.

There are two files (or, will be), in your /Scripts/OgreNav/ folder. OgreNavExample.iss and OgreNavExampleAdvanced.iss

• OgreNavExample.iss is a very basic example of how to use it, with nearly no options changed from the default.

function main(string _Location="WhereDoYouWantToGo")
{
	ogre navlib
	wait 5
	Obj_OgreCreateNavLibs:CreateNavLib[${Script.Filename}]
	Obj_OgreCreateNavLibs:CreateNavEntry[${Script.Filename}]
	
	OgreNavEntry:Set_Location["${_Location}"]
	call OgreNavLib.OgreNav OgreNavEntry
}

There are 3 parts to note, that will be required before using the Nav lib.

• Step 1: Make sure the navlib is loaded, and wait some indetermined amount of time for it to load.

	ogre navlib
	wait 5

• Step 2: Create the Nav lib
  • This creates 'OgreNavLib' for you.
  • See This link for members and methods of OgreNavLib.

	Obj_OgreCreateNavLibs:CreateNavLib[${Script.Filename}]

• Step 3: Create a navigation entry.
  • This is how you tell the nav lib where you want to go.
  • See This link for members and methods of OgreNavEntry.

	Obj_OgreCreateNavLibs:CreateNavEntry[${Script.Filename}]

The rest is pretty basic. You modify anything in NavLib/NavEntry, then you call OgreNav and pass it the Entry. Simple huh?

OgreNavLib - Methods and Members

Functions

• function:bool OgreNav(persistentref OgreNavEntry)
  • The "go" function. Requires being passed an OgreNavEntry.

Members

• member:bool Paused()
  • Check if OgreNavLib is paused.
  • Example: ${OgreNavLib.Paused}
• member:string Status()
  • Various status that are being reported by OgreNavLib. This will likely need testing to be very useful.
• member:bool RegionExists(string RegionName)
  • If you want to check if a region exists by name. For example: echo ${OgreNavLib.RegionExists["Point1"]} will return TRUE if the region exists, or FALSE if the region does not exist.

Methods

• method ListCustomNamedLocations()
  • Lists all Custom Name points to the console
  • If this would be useful to be dumped back as a variable, let me know and I can add one to return an index of strings.
• method Pause(bool PauseIt)
  • Pass TRUE to have it a pause status, or FALSE to have it resumed.
• method Reset()
  • Resets some internal values. Likely not ever to be used by a script, but may be if re-using the navlib within the same script.
• method Stop(string ReasonForStop=Stopped)
  • Used to stop movement.
• The rest below should be straight forward. They are for changing various values. If an explanation is required PM me.
  • Example: OgreNavLib:Set_TargetRequired[TRUE]
  • method Set_AllowFlyingOffMap(bool _Value)
  • method Set_AllowOffMapFudging(bool _Value=TRUE)
  • method Set_DistanceToMoveBackToPath(float _Value)
  • method Set_HeightPrecision(float _Value)
  • method Set_OffMapFudgeDistance(float _Value)
  • method Set_OffMapPrecision(float _Value)
  • method Set_Precision(float _Value)
  • method Set_PrecisionToDestination(float _Value)
  • method Set_StuckDistance(float _Value)
  • method Set_TargetRequired(bool _Value)
  • method Set_ForceLandAfterNav(bool _Value)
    • This will specifically try to land you after all navigation is done. You will want to make sure you do NOT enable this if you are trying to navigate to some where in the air, or it will land you right after.
• Currently not able to be updated by the user. But will be in the future.
  • method Set_OgreNavChecks(persistentref _ref)
  • method Set_OgreNavInformation(persistentref _ref)

OgreNavEntry - Methods and Members

Methods

• method Reset()
  • Resets everything to blank/default.
• method Set_Location(string _Location)
  • Sets the location by name.
    • Example: OgreNavEntry:Set_Location["Point1"]
• method Set_XYZ(float _X, float _Y, float _Z)
  • Sets the XYZ.
    • Example: OgreNavEntry:Set_XYZ[10,3,-248]