SXL Map Tools (Bills Tools) - SkaterXLModding/skater-xl-mapping-wiki GitHub Wiki

Welcome
FAQ
Known Bugs
Related Wiki Pages
External Information Sources

Welcome

This guide will serve as a detailed documentation source for, as well as offering a beginners guide to, using the SXL Map Tools package, commonly known as Bill's Tools. The SXL Map Tools package is a tool suite designed by Bill to help optimize spline generation without any paid plugins. It is important to keep two things in mind when using this tool suite:

It is constantly under development. Just like most other things SXL modding related, these tools are a volunteer project and always evolving. Remember to keep an eye out for updates. We will try to keep this wiki fully updated as often as possible, but it is likely that the documentation here may lag behind by a few days.
Bill's Tools splines simply semi-automate the Hondunes spline method. Although widely considered a different spline method, the rules of Hondunes still apply when working with this tool suite.

Installation

Installation of the SXL Map Tools package is quite straight forward. Before moving forward on installing the tool pack into an existing project, it is worth noting that there is a template project available. This comes with all layers, tags, and the full tool suite installed without the need for the user to set any of it up. If you are starting a new project, it is highly recommended to use this template as long as you want to use the SXL Map Tools package.

Before installing the package, install Git for your appropriate OS. Git is an open source version control system, that you should already have installed for [versioning your project].

To begin installation in Unity, go to Window > Package Manager

Next, click the + dropdown in the top left corner of the Package Manager window and select Add package from GIT URL

Paste this URL: https://github.com/billowper/SXL-Map-Tools.git

Now simply wait for the package to finish installing.

Overview

Very quickly, we will take a look at the over all parts and pieces that this tool suite is comprised of, what it offers mappers, and giving a brief overview of an efficient workflow with the SXL Map Tools. Although most commonly used for its efficient spline construction workflow, it offers a handful of other functionalities which all mappers can take advantage of. Due to this versatility of the tool, it is recommended to use on all SXL projects.

Top Bar

Once the plugin has been installed, a new tab will appear in the top bar called SXL, this is where the tools menu can be found.

Quick Export - This option allows for an easy export, the tool will automatically prep the currently active scene before exporting it, using the default export settings

Note: SXL Map Tools export automatically transfers the exported map file to the Maps folder

Test Export Process - Runs the functions to relocate spline objects to their required hierarchy

Add Grind Surface / Shift + G - Adds a Grind Surface component to the selected object

Note: Currently, using this function also auto-gens splines, do not use this on complex objects!

Tools Window - Opens the full SXL Map Tools window. Recommended to open this and attach it somewhere in your editor

Place Player Scale Reference at Cursor / Ctrl + G - Places an editor only scale reference at the current location of mouse cursor. Use the hotkey for this

SXL Map Tools Window

Tools

Use Version Numbering - With this function enabled, each time you export a scene, it will increase in version number by one, this is attached at the end of the scene as SceneName V#

Override Name - Override the name of the exported map file

Version Number - Current version number of the active scene

Run Game After Export - Once completed exporting, SXL will launch automatically

Export Map - Export the currently selected scene using the applied export settings

Note: SXL Map Tools export automatically transfers the exported map file to the Maps folder

Open Maps Folder - Opens your Maps folder in windows explorer

Note: All functions related to the Maps folder only work if your Maps folder is in the default location

Run SkaterXL - Runs your SXL application

Delete Previous Versions - Clears previous versions of the current scene map files from the Maps folder

Reset Version Number - Sets Version Number value back to 1

Settings

These settings are the preferences for GrindSpline Generation (Experimental)

Grind Spline Generation

AutoUpdateColliders - Automatically updates colliders on value changes

Note: Does not appear to be working currently, might be bugged (or the guide writer doesn't know how to use it)

Draw Generation Debug - When using GrindSpline Generation (Experimental), shows debug gizmos as visuals for how the code is identifying normals of the object being used

Note: These gizmos auto-hide if the mouse cursor is moved

Default Surface Settings

Is Edge - Used for collider generation as to whether the spline points are placed on the edge or not. If disabled, the collider will be centered on the spline. If enabled, the collider will generate with an edge along the spline

Auto Edge Alignment - If Is Edge is true, then this will be called to use code to detect which edge of the collider to align with the spline

Collider Type - Colliders can be generated with Box or Capsule primitives

Grindable Vertex Settings

These are values the GrindSpline Generation (Experimental) function uses to determine how splines will be auto-generated. Use at your own risk!

PointTestOffset -

PointTestRadius -

MaxHorizontalAngle - Maximum angle along the horizontal axis the generator will spline along before creating a separate spline

Note: For a visual of how this works, set this value over 90 on a box when generating splines to create one long spline, then lower it below 90 to generate separate splines

MaxSlope - Maximum angle along an edge the generator will spline before stopping.

IE: Useful for controlling generation on steep kinks or wallie edges. Setting value of >90 can have unpredictable results

MinVertexDistance - Minimum distance between vertices the generator will use for generating spline points. If two vertices are nearer than this value, only 1 will be used for splining

SkipExternalCollisionCheck -

Components

Grind Surface

The Grind Surface component is the parent component that is used to generate and control child splines.

Splines

Add GrindSpline - Creates a child GrindSpline object with the Grind Spline (Script) component applied

Draw GrindSplines - Enable spline drawing in the 3D Scene viewer

3D Scene Viewer Spline Drawing Controls

Shift+LMB: Place Point
V: Toggle Vertex Snapping
Space: Confirm
Esc: Cancel Drawing

Default Spline Settings

Surface Type - Sets the surface type of the spline, determining the sound made when grinded. Can be Concrete or Metal

Is Round - Sets the grind to being Round type, this determines if the map importer will generate a capsule or box collider

Don't overthink the logistics of this setting

Generate All Colliders - Generates all colliders for created splines parented to this surface

Generate All Colliders (Use Generation Settings) - Generates all colliders for created splines parented to this surface using the values set in GrindSplineGeneration

Destroy All & Reset - Destroys all parented spline objects and resets the surface

Beneath this, you can see each parented spline, generate colliders for them individually, and click them to highlight the corresponding object in the hierarchy.

GrindSpline Generation (Experimental)

Collider Type - Determines generated spline collider shape. Can be Box or Capsule primitives

Box settings

Width - Width of generated colliders

Depth - Depth of generated colliders

Capsule settings

Radius - Radius of generated colliders

Auto Detect Edge Alignment - If Is Edge is true, then this will be called to use code to detect which edge of the collider to align with the spline

Layer Mask -

Flip Edge - Inverts the edge selected by the generation to use for colliders. Does not work with Auto Detect Edge Aligntment enabled

Generate Splines - Automatically generates all splines for the selected surface

Warning: This is an experimental function and is only recommended on simple objects. Does not work well on rails, and will certainly crash Unity on complex surfaces

Grind Spline

Spline Creation

The most popular function of SXL Map Tools is the ability to easily generate Hondunes style splines in a more user friendly manner. The tool suite handles point placement, collider generation, and hierarchy organization all for the user.

Spline Basics

To familiarize oneself with the workflow involved, it is recommended to start by doing a very basic spline, on a flat box feature.

Note: Simple boxes and hubbas can actually use the GrindSpline Generation (Experimental) auto-spline function quite effectively, but for the sake of learning it is best to practice the manual method here

Select the desired object. In the inspector, select Add Component, search for grind, and select GrindSurface

Select Draw GrindSplines. Highlight the 3D scene viewport as the active window (you can do this by adjusting the view). Next press V to enable vertex snapping. Now we can simply Shift left click to place points on vertices of the model. Once points are place appropriately for one edge spline, press Space to complete the spline. A blue line with gizmos will indicate the placed spline.

After completing the spline with Space, you can begin placing the next spline along another edge without exiting the draw mode. This allows the user to very quickly place all the splines required for an object. In this case, we will just place a spline along each edge of the box.

Once all desired splines have been placed, press Esc to exit draw mode. Clicking Generate All Colliders will create the colliders aligned with the splines. By default, the colliders will not be edge based, so we must do one of two things: change the collider settings per spline, or using the surface collider settings. On a simple object like this box we can simply check the Is Edge and Auto Detect Edge Alignment, then use the Generate All Colliders (Use Generation Settings) to generate new colliders using the settings specified.

Important Notes

As of the current build of SXL, the map importer automatically generates spline colliders for Hondunes style splines (which this tool utilizes). This means that if you create your own colliders, the game will overlap another collider over them. Which can lead to "lazy" style grind animations. As of the current date there is no known reliable solution to the bug other than not generating your own colliders.

FAQ

How do I add coping with Bill's Tools?

As of the current SXL version, v1.0.1.2, there is no way to create coping grinds without Dreamteck. This is due to a core function of the map importer code, and there is no known workaround.

I don't see any Scene View UI elements

Refer to the UI Scale Issue section of Known Bugs

Known Bugs

UI Scale Issue

If you can not see the UI elements in the 3D scene view, it is due to the Unity UI auto scaling. This is most common on high resolution displays. There is a fix, although it could have some interesting side effects related to your project UI scale.

Navigate to the Edit > Preferences tab at the top of your screen

In Preferences, go to the UI Scaling tab. Disable Use default desktop setting and set the custom scaling value to 100% from the dropdown. Upon restarting Unity, your UI should be rescaled and the missing and misaligned gizmos will be fixed.