View source for Pathfinding Tools in the Second Life Viewer

{{Pathfinding Nav}}
__TOC__
{{KBnote|The Viewer tools described here are not yet available in a public Second Life Viewer build, but will be soon. }}
== Introduction ==
For pathfinding, each region has a navigation mesh, commonly referred to as a "'''navmesh'''".  The '''navmesh''' is a representation of the region's geometry generated and used by the physics simulator to determine paths for the pathfinding characters.  The navmesh may be in one of the following three states:

* Up-to-date
* Has pending changes
* Building ''(a.k.a. rebaking)''

The navmesh will transition through these states according to the following diagram:

[[File:Navmesh_transitions.png|alt=Second Life Pathfinding NavMesh Transitions|Second Life Pathfinding NavMesh Transitions]]

Five new elements have been added to the SL Viewer interface to communicate the navmesh state for the current region.  These new elements are:

* icon representations of the pathfinding region state for the SLURL bar
* a "Rebake region" button that appears above the lower toolbar
* a right-click context menu option addition
* an additional field on the Build floater
* an additional field on the Object Profile floater

In addition to these new elements, three new floaters allow users to more efficiently create, visualize, test, and debug pathfinding-enabled characters.  These tools are not required to create pathfinding behaviors but are particularly useful to builders and experienced creators in Second Life.  These new floaters are:

* Pathfinding linksets
* Pathfinding characters
* Pathfinding view / test


== Pathfinding UI Elements ==

'''Note that other residents editing pathfinding objects on the same region may create pending changes to the navmesh.''' When this occurs, all residents on the same region and with build rights will see the appropriate SLURL bar icons and rebake region button.

=== Pathfinding Icons in SLURL Bar ===

The SLURL bar indicates the three pathfinding states of the current region.
# '''Navmesh is up-to-date''' The current region's navmesh is up-to-date.  No icon is shown as this is the expected default state. <br> [[File:Pathfinding-clean-region-1.png|alt=Second Life URL Bar with Up-to-Date NavMesh Icon|Second Life URL Bar with Up-to-Date NavMesh Icon]]
# '''Navmesh has pending changes''' The region has pending changes that have not yet been baked into the navmesh.  A pathfinding icon with a construction symbol is shown. <br> [[File:Pathfinding-dirty-region-1.png|alt=Second Life URL Bar with Pending Changes Icon|Second Life URL Bar with Pending Changes Icon]]
# '''Dynamic pathfinding is disabled''' The region has dynamic pathfinding disabled.  Pathfinding characters will not work as expected.  A pathfinding icon with a disabled symbol is shown.<br> [[File:Pathfinding-disabled-region-1.png|alt=Second Life URL Bar with Pathfinding Disabled Icon|Second Life URL Bar with Pathfinding Disabled Icon]]

=== Rebake Region Button ===

When a region has pending changes, the appropriate icon will be shown in the SLURL bar, as described above.  In addition, if the user has build rights for any parcel on the current region, the user will also be able to see a "Rebake region" button that displays above the lower toolbar.

[[File:Rebake-button-1.png|alt=Second Life Rebake Region button that allows permitted users to rebake pathfinding changes into the navmesh]]

When the user clicks this button, a request is sent to the region to rebake the navmesh for the current region.  As rebaking a region may be a time intensive process, the button will change to indicate "Region is rebaking" during this server process.  After the rebaking is complete, this button on the viewer will vanish.

[[File:Rebaking-button-1.png|alt=Second Life Region is Rebaking button that indicates that the current region is rebaking its navmesh]]

=== Right-click context menu behavior ===

When right-clicking on an object in-world, pathfinding-specific menu options may be included in the pop-up context menu.

If the user right-clicks on a '''linkset''' object in-world, a menu option "Show in linksets" will allow the user to open the Pathfinding Linksets floater with the current object selected.

[[File:Right-click-show-in-linksets-1.png|alt=Second Life Context Menu with Show in Linksets floater menu option]]

If the user right-clicks on a pathfinding '''character''' object in-world, a menu option "Show in characters" will allow the user to open the Pathfinding Characters floater with the current object selected.

[[File:Right-click-show-in-characters-1.png|alt=Second Life Context Menu with Show in Characters floater menu option]]

=== Additional field on the Build floater ===

The Build floater has also been updated with an additional field indicating the pathfinding attributes of the current object.

The following image is a screenshot of the Build floater with a ''character'' object selected.

[[File:Build-floater-character-1.png|alt=Build floater with pathfinding attribute character|Build floater with pathfinding attribute character]]

The following image is a screenshot of the Build floater with an object that ''affects navmesh'' selected.  This object could be a ''walkable'', ''static obstacle'', ''material volume'', or ''exclusion volume''.

[[File:Build-floater-affects-navmesh-1.png|alt=Build floater with pathfinding attribute affects navmesh|Build floater with pathfinding attribute affects navmesh]]

{{KBwarning|For linksets that do affect the navmesh, it will be impossible to modify the object across the region boundary.  The user and the object affecting a navmesh must be in the same region to enable modification of the object.  This will be indicated on the General tab of the Build floater as illustrated in the following screenshot.}}
[[File:Build-floater-region-boundary-1.png|alt=Build floater indicating that the user cannot modify object across a region boundary|Build floater indicating that the user cannot modify object across a region boundary]]

=== Additional field on the Object Profile floater ===

Similar to the afore-described Build floater, the Object Profile floater has also been updated with an additional field indicating the pathfinding attributes of the current object.

The following image is a screenshot of the Object Profile floater with an ''affects navmesh'' object selected.

[[File:Object-profile-1.png|alt=Object Profile floater with pathfinding attribute affects navmesh|Object Profile floater with pathfinding attribute affects navmesh]]

== Pathfinding Floaters == 

These three pathfinding floaters may all be accessed through the Build->Pathfinding menu in the Project Viewer - Pathfinding.

[[File:Build-menu-pf-selected-1.png|alt=Second Life Build Menu with new Pathfinding menu items|SL Build -> Pathfinding Menu]]

<br><br>

=== Pathfinding Linksets Floater ===

==== Overview ====

The intent of the Pathfinding Linksets floater is to give advanced users and builders the ability to customize an area to achieve interesting effects with pathfinding-enabled characters.

The floater displays information for all linksets within the current region for which the user has the ability to alter.  The table reports useful information including
* Linkset Name
* Description
* Owner
* Land Impact
* Distance from the resident's avatar
* Linkset Use
** Potential values
*** Walkable
*** Static Obstacle
*** Movable Obstacle
*** Material Volume
*** Exclusion Volume
*** Movable Phantom
* Walkability Coefficients
** Character Type A ''(example use: humanoid)''
** Character Type B ''(example use: creature)''
** Character Type C ''(example use: mechanical)''
** Character Type D ''(example use: other)''

Additionally, selecting any linksets within the floater will also select the object(s) within the Viewer.

[[File:Linksets-floater-2.png|alt=Pathfinding Linksets floater|Pathfinding Linksets]]

<br><br>

==== Controls ====

{{:Viewerhelp:Pathfinding linksets}}

==== Example use ====

The advanced users and builders will use the Pathfinding Linksets floater to customize areas to create interesting effects for pathfinding-enabled characters.

For instance, imagine the scenario of a builder constructing a single room in a pathfinding-enabled house.  For the single room, the builder would use the following types as follows:

{|border="1"
! Linkset Use !! Description
|-
|width="200" align="center" | Walkable || align="left" | The floor linkset would be set to be <b>Walkable</b> to allow characters to move across the floor.
|-
|width="200" align="center" | Static Obstacle || align="left" | A desk linkset in the room would be set to be <b>Static Obstacle</b> to block characters from walking through or across the object.

<b>NOTE</b> Any object that should block character movement and that does not move should be marked as Static Obstacle to improve performance of pathfinding characters.
|-
|width="200" align="center" | Movable Obstacle || align="left" |  A door linkset in the room would be set to be <b>Movable Obstacle</b>.  This will still block characters but, in contrast to Static Obstacles, Movable Obstacles will allow the linkset itself to move.  In the case of the door, this will allow the door to open and close, but will still prevent characters from walking through the door.
|-
|width="200" align="center" | Material Volume || align="left" |  <b>Material Volumes</b> are phantom objects that can be used to affect the walkability coefficients of intersecting objects.  Imagine that the builder applied a texture to the floor.  Also, imagine that the floor texture includes small throw rug in the middle of the room.  (The builder did not want to create a separate object for the rug, so is using a texture on the floor to give the appearance of a rug).  The builder can then create a Material Volume object intersecting the floor at the location of the rug.  Then, by setting a lower walkability coefficient for the Material Volume, the builder will create the affect of slowing down characters as the characters traverse across the painted rug area.
|-
|width="200" align="center" | Exclusion Volume || align="left" |  <b>Exclusion Volumes</b> are phantom objects that can be used to create areas where characters are prevented from moving.  For instance, the builder can use an Exclusion Volume to create a section of the room where avatars would be able to move, but characters would be blocked from following.
|-
|width="200" align="center" | Movable Phantom || align="left" |  <b>Movable Phantoms</b> are phantom objects that have no affect on pathfinding-enabled characters.
|}
<br><br>
In addition to linkset use attributes, builders can achieve additional effects by modifying the walkability coefficients for linksets.  The walkability coefficients are values, ranging from 0% to 100%, that affect a characters speed.  A walkability coefficient of 50% will reduce a character's speed by half while the character is traversing across the linkset.
<br><br>

=== Pathfinding Characters Floater ===

==== Overview ====
The intent of Pathfinding Characters floater is primarily for users to locate characters moving throughout a region and to identify the CPU cost of characters affecting the performance of a region.

The floater displays information for all characters within the current region for which the user has the ability to manipulate.  The table reports useful information including
* Character Name
* Description
* Owner
* CPU Time
* Altitude

[[File:Characters-floater-1.png|alt=Pathfinding Characters floater|Pathfinding Characters]]
<br><br>
==== Controls ====

{{:Viewerhelp:Pathfinding characters}}

==== Example use ====
# If a region owner has created a pathfinding-enabled character but is unable to find the character within the region, the Characters floater can be used to locate and select the character.
# Additionally, the Pathfinding Characters floater reports the CPU time cost for each character within the region.  This functionality can be used by advanced users to identify which characters are impacting performance the most.

=== Pathfinding View/Test Floater ===

==== Overview ====

The intent of the Pathfinding View/Test floater is for advanced users who are building pathfinding-enabled objects and characters.

This floater consists of 3 basic areas.

# Status area (illustrating both the Viewer and Simulator status of the region's navmesh)
# View tab Controls
# Test Path tab Controls

The following image is a screenshot of the Pathfinding View/Test floater with the navmesh displayed.

[[File:View-nav-mesh-1.png|alt=Pathfinding View/Test floater with the navmesh displayed|Pathfinding View/Test with navmesh displayed]]

The following image is a screenshot of the Pathfinding View/Test floater with the pathfinding object types displayed.

[[File:View-pf-types-1.png|alt=Pathfinding View/Test floater with the pathfinding object types displayed|Pathfinding View/Test with the pathfinding object types displayed]]

The following image is a screenshot of the Pathfinding View/Test floater with a test path displayed.

[[File:View-test-path-1.png|alt=Pathfinding View/Test floater with a test path displayed|Pathfinding View/Test with a test path displayed]]

<br><br>
==== Controls ====

{{:Viewerhelp:Pathfinding edit and test}}

==== Example Use ====

# The advanced user will use the Visualization controls to visualize how the navmesh and related permanent objects have been generated.  By seeing this visualization of how the physics engine interprets the navigation information, the advanced user can understand how to better customize the pathfinding-enabled objects to obtain the desired behaviors of characters.
# The advanced user will use the Test Tab to visualize how a test character would choose the path between selected start and end points.

<br><br>

== Known Issues ==

{| style="border-style:solid;border-width:2px 0 2px 0px;" 
! style="border-style:solid;border-width:0 0 1px 0" width="100" | JIRA
! style="border-style:solid;border-width:0 0 1px 0" width="500" | Summary
! style="border-style:solid;border-width:0 0 1px 0" | Hardware
|-
| style="border-style:solid;border-width:0 0 1px 0;border-color:rgb(200,200,200)" | [https://jira.secondlife.com/browse/PATH-572 PATH-572]
| style="border-style:solid;border-width:0 0 1px 0;border-color:rgb(200,200,200)" | Underwater 'Walkables' shapes are reflected about the water plane
| style="border-style:solid;border-width:0 0 1px 0;border-color:rgb(200,200,200)" | 
|-
| style="border-style:solid;border-width:0 0 1px 0;border-color:rgb(200,200,200)" | [https://jira.secondlife.com/browse/PATH-643 PATH-643]
| style="border-style:solid;border-width:0 0 1px 0;border-color:rgb(200,200,200)" | Changes in Preferences dialog stops work of Pathfinding View/Test functionality
| style="border-style:solid;border-width:0 0 1px 0;border-color:rgb(200,200,200)" | 
|-
| style="border-style:solid;border-width:0 0 1px 0;border-color:rgb(200,200,200)" | [https://jira.secondlife.com/browse/PATH-659 PATH-659]
| style="border-style:solid;border-width:0 0 1px 0;border-color:rgb(200,200,200)" | navmesh being drawn over worn flexi prims and under avatar
| style="border-style:solid;border-width:0 0 1px 0;border-color:rgb(200,200,200)" | 
|-
| style="border-style:solid;border-width:0 0 1px 0;border-color:rgb(200,200,200)" | [https://jira.secondlife.com/browse/PATH-781 PATH-781]
| style="border-style:solid;border-width:0 0 1px 0;border-color:rgb(200,200,200)" | Group-owned objects appear to be owned by 'Unknown' in pathfinding linksets floater
| style="border-style:solid;border-width:0 0 1px 0;border-color:rgb(200,200,200)" | 
|-
| style="border-style:solid;border-width:0 0 1px 0;border-color:rgb(200,200,200)" | [https://jira.secondlife.com/browse/PATH-790 PATH-790]
| style="border-style:solid;border-width:0 0 1px 0;border-color:rgb(200,200,200)" | Physics capsule rendering of character shapes is broken after zooming
| style="border-style:solid;border-width:0 0 1px 0;border-color:rgb(200,200,200)" | 
|-
| style="border-style:solid;border-width:0 0 1px 0;border-color:rgb(200,200,200)" | [https://jira.secondlife.com/browse/PATH-812 PATH-812]
| style="border-style:solid;border-width:0 0 1px 0;border-color:rgb(200,200,200)" | Show capsules option creates black capsule instead of blue
| style="border-style:solid;border-width:0 0 1px 0;border-color:rgb(200,200,200)" | ATI Radeon X300 Video card <br> ATI Radeon X600 Video card
|-
| style="border-style:solid;border-width:0 0 1px 0;border-color:rgb(200,200,200)" | [https://jira.secondlife.com/browse/PATH-813 PATH-813]
| style="border-style:solid;border-width:0 0 1px 0;border-color:rgb(200,200,200)" | Enable Debug GL crashes the viewer to the desktop
| style="border-style:solid;border-width:0 0 1px 0;border-color:rgb(200,200,200)" | Mac Pro running 10.7.4 with AMD Radeon HD5770 <br> PC Clone running XP Pro with GeForce2 Ultra
|-
| style="border-style:solid;border-width:0 0 1px 0;border-color:rgb(200,200,200)" | [https://jira.secondlife.com/browse/PATH-814 PATH-814]
| style="border-style:solid;border-width:0 0 1px 0;border-color:rgb(200,200,200)" | Sony VAIO PCG-71211 laptop displays black environment
| style="border-style:solid;border-width:0 0 1px 0;border-color:rgb(200,200,200)" | Sony VAIO PCG-71211 with AMD Radeon HD5650M Mobile graphics
|-
| style="border-style:solid;border-width:0 0 1px 0;border-color:rgb(200,200,200)" | [https://jira.secondlife.com/browse/PATH-821 PATH-821]
| style="border-style:solid;border-width:0 0 1px 0;border-color:rgb(200,200,200)" | Toshiba Satellite L645 laptop displays black environment
| style="border-style:solid;border-width:0 0 1px 0;border-color:rgb(200,200,200)" | Toshiba Satellite L645 laptop with AMD Radeon HD 4200 Mobile graphics
|-
| style="border-style:solid;border-width:0 0 1px 0;border-color:rgb(200,200,200)" | [https://jira.secondlife.com/browse/PATH-822 PATH-822]
| style="border-style:solid;border-width:0 0 1px 0;border-color:rgb(200,200,200)" | Configuration with ATI Radeon 7500 can launch Viewer, serious GFx issues
| style="border-style:solid;border-width:0 0 1px 0;border-color:rgb(200,200,200)" | AMD Athlon64 3000+ with ATI Radeon 7500 video card
|}