Lucas' Simpsons Hit & Run Model Builder

This book contains information about Lucas' Simpsons Hit & Run Model Builder. This tool is used to build custom maps, cars and more from various input file types. THIS TOOL IS NOT CURRENTLY RELEASED.

Introduction

This tool is not currently released and this documentation exists to outline how to use it ahead of it's release.

What is the Model Builder?

Lucas' Simpsons Hit & Run Model Builder is a tool that allows you to build maps, cars and state props for The Simpsons: Hit & Run.

This is a command line tool that is powered by XML Rules files that define input files and how to output their contents.

The tool includes a large array of base rules as well as special components for use in Input SketchUp Models.

Power users are able to modify the included rule sets to their heart's desire but it's important to keep in mind that this documentation assumes that you are using the stock rules.

Getting Started

Tutorials on how to use the Model Builder to create custom maps can be found in the Map Building Tutorials chapter.

Command Line Arguments

This is a list of Command Line Arguments for the Model Builder and what their functions do.

Command Line Argument Function
-log Enables logging to the log file. Enabled by default unless -nooutput is enabled.
-nolog Disables logging to the log file. Enabled by default if -nooutput is enabled.
-nooutput Prevents the Model Builder from building any output files.
-nopause Suppresses the Press any key to continue . . . prompt at the end of the building process.
-sketchup16 Forces the Model Builder to use the SketchUp 2016 API.
-sketchup17 Forces the Model Builder to use the SketchUp 2017 API. Enabled by default if you're using Windows Vista or newer.

Configuration

Configuration

Pre-defined Variables

Variable Name Value
ModelBuilderPath This variable will be set to the folder the tool's executable is located in.
GamePath This variable will be set to the path your install of the game is located at.

Input SketchUp Models

Input SketchUp Models

Special Components

The Model Builder includes a special library of components for use in Input SketchUp Models.

Component Name Purpose
BillboardQuad Used to represent Billboard Quads. Can be alone or inside a BillboardQuadGroup structure.
Camera Used in an AnimatedCamera Structure to represent a position for the camera.
CollisionBox Used to represent Collision Oriented Bounding Boxes inside various types of structures.
CollisionCylinder  Used to represent Collision Cylinders inside various types of structures.
CollisionSphere Used to represent Collision Spheres inside various types of structures.
Locator Used to represent a locator. Depending on the type of locator, this may be by itself or within a Locator structure.
RectTriggerVolume Used to represent a rectangular Trigger Volume in a Locator structure.
SphereTriggerVolume. Used to represent a spherical Trigger Volume in a Locator structure.
Input SketchUp Models

Group Tags

When inputting a SketchUp Model, your model can utilize various tags in Group names to invoke special rules and build processes. For example, this can allow you to tag a road mesh as something that should be part of a HUD Map.

The Model Builder includes a wide array of tags in plain-text XML files that you can include and use to output your models. Certain tags require more complex group structures which will be listed where necessary.

This page is grouped by what file must be included for the rules to be accessible.

AnimatedCameras.xml

This file contains rules related to building Animated Cameras.

Tag Requirements Function Example
[AnimatedCamera] [CameraTime] Must be on an AnimatedCamera Structure. Creates an Animated Camera from the contents of the structure that can be used for Mission Start Cameras. See Structure: AnimatedCamera.
[OrientToPath] Must follow an [AnimatedCamera] tag on an AnimatedCamera Structure. Makes the camera oriented to the Path.  

HUDMap.xml

This file contains rules related to building HUD Maps.

Tag Requirements Function Example
[NonHUDMapMesh]   Makes it so the meshes inside the group will not get put on the HUD Map. Hidden Road [NonHUDMapMesh]
[Road]   Applies road colored Vertex Colours to this group on the HUD Map. Road [Intersect] [Road]
[Sidewalk]   Applies sidewalk colored Vertex Colours to this group on the HUD Map. Sidewalk [Intersect] [Sidewalk]
[Building]   Applies building colored Vertex Colours to this group on the HUD Map. House [Intersect] [Building]

Zone.xml

This file includes various other XML files that register tags related to Zones.

General Tags

Tag Requirements Function Example
 [ExcludeFromBounds]      

Intersect Tags

These are the tags related to building Intersect collision.

These are specified in Internal\Intersects.xml.

Tag Requirements Function Example
[NonWorldMesh]   Makes it so within a group or component will not be built into a Static Entity. Group [NonWorldMesh]
[Intersect]   Makes Intersect collision with a Surface Type of 0 out of the contents of the group. Ground [Intersect]
[Grass] Must be placed after an [Intersect] tag in a group name. Makes the Intersect collision have a Surface Type of 1. Grass [Intersect] [Grass]
[Sand] Must be placed after an [Intersect] tag in a group name. Makes the Intersect collision have a Surface Type of 2. Sand [Intersect] [Sand]
[Water] Must be placed after an [Intersect] tag in a group name. Makes the Intersect collision have a Surface Type of 4. Water [Intersect] [Water]
[Dirt] Must be placed after an [Intersect] tag in a group name. Makes the Intersect collision have a Surface Type of 7. Dirt [Intersect] [Dirt]
[SurfaceType] [ID] Must be placed after an [Intersect] tag in a group name. Makes the Intersect collision have the specified Surface Type in place of ID. IDKMan [Intersect] [SurfaceType] [11]

Static Entity Tags

These are the tags related to controlling the way Static Entities are built.

By default, any meshes with a zone are split by their materials into Static Entities. These tags are just for fine tuning how your map is built.

These are specified in Internal\StaticEntities.xml.

Tag Requirements Function Example
[StaticEntity]   Makes the meshes inside the group get put into a separate Static Entity from the rest of the Zone. House [StaticEntity]
[StaticEntityGroup]   Makes the meshes inside the group get split by shader and put into separate Static Entites from the rest of the Zone. House [StaticEntityGroup]
Input SketchUp Models

Structure: AnimatedCamera

Synopsis

This page documents the group structure required to use an [AnimatedCamera] tag to build a mission start camera.

Requirements

  • A group tagged CameraName [AnimatedCamera] [Time].
    • Replacing Time with an amount of seconds the camera will take to animate.
  • A group named Path containing a single connected series of lines that represent the path of the camera.
  • 2 or more Camera components inside the AnimatedCamera group.
    • One camera should be named Start and one should be named End.
      • These should be placed at opposite ends of the group named Path.
    • Any additional Camera components can be used to fine tune the camera's position as it moves along its Path.

Example

Group Structure

This is an example of how the group structure in the Outliner could look.

LucasModelBuilder_Structure_AnimatedCamera_GroupLayout.png

3D View

This is an example of how the 3D view of the camera could look.

LucasModelBuilder_Structure_AnimatedCamera_3DView.png

 

 

 

Map Building Tutorials

Map Building Tutorials

Tutorial 1: Making a Basic Map

Introduction

This tutorial will guide you through the bare minimum steps to make a basic custom map work in-game.

By the end of this tutorial, you should have a small map that is just a square piece of ground with a couple locators.

Note: Missions will not yet work in this map and it will not have a custom HUD map.

Prerequisites

You will need a PC copy of The Simpsons: Hit & Run as well as the following tools to accomplish the steps in this tutorial.

  • The Simpsons: Hit & Run for PC
  • Lucas' Simpsons Hit & Run Mod Launcher
  • Lucas' Simpsons Hit & Run Model Builder
  • SketchUp Make 2017
    • Knowledge of how to use SketchUp in general will help as well as these tutorials may not go into very much detail about the specifics of how to use it.
  • A Text Editor, we recommend Notepad++.

Part 1: The Mod

To actually play our map in-game, we'll first need a basic mod to start with. We've gone ahead and created a basic mod for these purposes that you can download from the sidebar of this page (Tutorial 001 Starter.zip) .

This mod contains the following:

  • A basic Meta.ini that requires the CustomFiles hack.
  • A set of Level scripts to load everything needed for our map.
  • A couple dummy missions with no objectives that will let us jump into our map by creating a new game from the main menu or by selecting L1M1.
  • A folder named "_Assets" that you'll work out of.

Part 2: The SketchUp File

Step 1: Setting up SketchUp

SketchUp's interface is very customizable so depending on your chosen layout you may not have certain important panels in view. We'd like to make a couple recommendations for the purposes of these tutorials.

Since the Model Builder relies heavily on group names and tags within them to work we'd first like to recommend that you keep the Outliner easily accessible. If you don't currently have a tray with the Outliner in it, you can go to Window > New Tray... to create one containing it. You may also want the Entity Info panel in the same tray as it will make editing attributes of the currently selected object easier.

With large models that have many thousands of groups, you may experience slowdown having the Outliner open so it may be good to get used to minimizing it by clicking the arrow near its header when you're not using it.

You will also want the Materials and Components panels accessible. You can technically put these in the same tray though if you have a good amount of screen real estate, it might be better to make another new tray containing just them.

Also note that all new models start with a Component named "Chris". He's not really relevant to what you're going to be doing and you can leave him there or delete him, it's up to you.

Step 2: Save the model

You haven't done anything yet but it's good to start by saving your model. For the purposes of these tutorials, you should save it as "Map.skp" in the "_Assets" folder of the mod you downloaded in Part 1.

Step 3: Terrain

You'll want to start by making some basic "terrain" in your SketchUp model, for the purposes of this tutorial, you should use a flat rectangle (though you could really use whatever you want).

MBTut001_FlatPlane.png

Step 4: Setting up the groups

Now that you have some "terrain" you'll want to group it properly so that you can build it into a zone later. Select the square, right click it and click "Make Group". Then double click the group to focus it and repeat this step. This will create a group within a group.

The reason you do this is so that you can use the outer group to represent the zone and the inner group to represent Intersect (ground) collision. To do that, you will want to name the outer group Zone001and name the inner group Ground [Intersect]. Once you've done that, your Outliner should look like this:

MBTut001_OutlinerNames.png

By default, everything within any group that represents a Zone will become a Static Entity model in the map. In this case however, you use the[Intersect] Group Tag to tell the Model Builder that the contents of this group should also be made into Intersect collision. We're not going to go very in depth with these during this tutorial but you can do some pretty complex stuff with them!

With those groups setup, that's the contents of our first zone done for now.

Step 5: Adding a couple locators

The scripts included in the mod from Part 1 reference a couple locators to specify where the player and their car should start in the level. You're also going to create those with the Model Builder using one of its Special Components.

Go to File > Import and navigate to the "Components" folder next to the Model Builder's executable. From there import "Locator.skp" into your model.

Now go to the Components panel and click the little house icon to bring up the list of components in the current model. If you imported it correctly, you should see "Locator" in this list.

4JYK6nPfMSDZKdsH-MBTut001_ComponentsInModel.png

Now click on it and drag a couple out onto the terrain you created in Step 3.

We're going to use these two locators as our player start and car start locators. You'll want to name one of them level1_homer_start [CarStart]and name the other one level1_carstart [CarStart]. The [CarStart] tag here tells the Model Builder to make "Car Start" locators which, despite their name, are also used for character starts.

Now that they're named and tagged select both of the instances, right click and click "Make Group". Name this group "Level" so we can build them into their own P3D file later. With all of that done, your Outliner should now look like this:

EjqzL9aDZhRtjOMi-MBTut001_OutlinerNames2.png

Step 6: Save again!

Make sure you save everything you've done so far if you haven't already.

Part 3: Configuring the Model Builder

Step 1: Creating the build files

To start, you want to create an XML file that will contain all of your rules for the Model Builder and a BAT file to actually launch the tool and tell it about your rules.

For now, just make a bare bones XML file that just has a root node:

<?xml version="1.0" encoding="UTF-8" ?>
<Build>
	
</Build>

Save this as "Build.xml" into the "_Assets" folder next to your SketchUp file.

Then make a BAT file that launches the Model Builder with "Build.xml" as a command line argument:

@"C:\path\to\LSHaRMB.exe" "Build.xml"

You'll need to manually replace the path with where-ever you put the Model Builder. Save this as "Build.bat" when you're done.

Once those are saved, running Build.bat should work and you should get an output that looks something like this:

[12:58:35 PM] MESSAGE: Loading SketchUp SDK DLL (64-bit) 17.0.18899.0...
[12:58:35 PM] MESSAGE: Processing outputs...
[12:58:35 PM] MESSAGE: Processing file outputs...
[12:58:35 PM] SUCCESS: Completed in 25.2060558021864 ms.

Obviously, you haven't told the tool to do anything yet so it hasn't actually created any output files. This is just to make sure that the BAT file is working as intended.

Step 2: Including the base Zone rules

Before you write any of your own rules, you'll want to include some of the tool's base rules. Simply add an Include element in the root node of the Build file you created in the last step and set the path to Zone.xml.

	<!-- Use the ModelBuilderPath variable to easily fill in the path to the tool's folder -->
	<Include Path="$(ModelBuilderPath)\Rules\Zone.xml"/>

This file contains all the necessary definitions to build Zones.

Step 3: Specifying output files and zones.

The next step is defining what the output files we're going to be building. In this case we're going to be building the Terra file, a single zone and a locators file.

	<!-- Specify output files -->
	<OutputPure3DFile Name="Terra" Path="$(OutputPath)\L1_TERRA.p3d"/>
	<OutputPure3DFile Name="Zone001" Path="$(OutputPath)\l1z1.p3d">
		<!-- Tell the tool that this file requires the Terra file to work -->
		<!-- This allows it to place textures/shaders used in multiple regions in the Terra file to save space -->
		<RequiredOutputPure3DFile Name="Terra" Textures="true" Materials="true" Lights="true"/>
	</OutputPure3DFile>
	<OutputPure3DFile Name="Level" Path="$(OutputPath)\missions\level01\level.p3d" />

You also want to define some information about the map and some zones for it, assigning each one to output in the appropriate OutputPure3DFile.

	<!-- Define the map -->
	<!-- This gives you control what file the k-d tree goes in, the size of its tree nodes and how many DynaPhys are allowed in each node -->
	<HitAndRunMap Name="Map" TreeMinimumNodeSizeX="20" TreeMinimumNodeSizeZ="20" TreeDynaPhysEntityLimit="10">
		<OutputPure3DFile Name="Terra"/>
	</HitAndRunMap>
	
	<!-- Define zones -->
	<!-- While things can be output directly into P3D files, outputting them into a zone instead makes them get included in the map's k-d tree -->
	<!-- Which is VERY important of course -->
	<!-- We don't need to do this for our Level OutputPure3DFile though since it's just going to contain locators and no world stuff -->
	<HitAndRunZone Name="Terra" Map="Map">
		<OutputPure3DFile Name="Terra"/>
	</HitAndRunZone>
	<HitAndRunZone Name="Zone001" Map="Map">
		<OutputPure3DFile Name="Zone001"/>
	</HitAndRunZone>

With these rules in place, the tool will now build empty P3D files to those paths. That's progress but you still need to tell it what to put in those files/zones.

Step 4: Making a light group and vertex colors

Before you handle how things are going to be built, you'll need a Light Group and Vertex Colour rules that reference them. This light group will be used to apply vertex colors to your map's models as well as being the actual light group used to dynamically light cars and characters in the world.

	<!-- Specify the Light Group and name it -->
	<LightGroup Name="Level1">
      	<!-- These lights are more or less equivalent to the "sun" light group in the original game's L1_TERRA -->
		<AmbientLight Name="Ss_ambientLightShape1" Red="89" Green="89" Blue="89"/>
		<DirectionalLight Name="Simpsons_sun_directionalShape3" Red="89" Green="89" Blue="89" DirectionX="0" DirectionY="-0.5" DirectionZ="-0.866"/>
		<DirectionalLight Name="Simpsons_sun_directionalShape2" Red="140" Green="140" Blue="140" DirectionX="-0.75" DirectionY="-0.5" DirectionZ="0.433"/>
		<DirectionalLight Name="Simpsons_sun_directionalShape4" Red="140" Green="140" Blue="140" DirectionX="0.75" DirectionY="-0.5" DirectionZ="0.433"/>
		
      	<!-- Specify and output file and chunk name to build this group into -->
      	<OutputPure3DFile Name="Terra" ChunkName="sun"/>
	</LightGroup>
	
	<!-- Specify VertexColours rules that reference that light group -->
	<VertexColours Name="World" Light="Level1" LightAbsolute="true"/>

Step 5: Specifying a fallback material

Your map doesn't have any materials yet if you've been following this guide so you probably want to specify a material that the tool can fall back to for faces that don't have any.

	<!-- Make a white material -->
	<Material Name="Null" Red="255" Green="255" Blue="255"/>

Step 6: Specifying input files

Now you'll want to specify a couple input files.

	<!-- Of course you want to input your Map's SketchUp file -->
	<!-- Note that this path is relative to the XML file this element is in -->
	<!-- Since the SKP file is right next to it, we just put "Map.skp" -->
	<InputSketchUpModel Name="Map" Path="Map.skp"/>
	
	<!-- You'll also want to input a couple files from the original game -->
	<!-- This will make sense in step 8 so stay tuned -->
	<InputPure3DFile Name="L1_Terra" Path="$(GamePath)\art\L1_TERRA.p3d" />
	<InputPure3DFile Name="L1_Level" Path="$(GamePath)\art\missions\level01\level.p3d" />

Step 7: Defining model output instructions

The next step is defining the instructions for outputting your SketchUp file.

	<!-- Instruction set used for each zone -->
	<ModelOutputInstructions Name="Zone">
		<!-- Use the instructions we included from "$(ModelBuilderPath)\Rules\Zone.xml" above -->
		<ExecuteInstructions Name="BaseZone"/>
		
		<!-- Set the vertex colors (lighting) of everything to the ones defined above -->
		<SetParameter Name="VertexColours" Value="World"/>
		
		<!-- Set the fallback material (for faces with no material) to the "Null" material created above -->
		<SetParameter Name="FallbackMaterial" Value="Null"/>
	</ModelOutputInstructions>
	
	<!-- Main instruction set -->
	<!-- Execute all of these instructions on the InputSketchUpModel named "Map" -->
	<SketchUpModelOutput InputSketchUpModel="Map">
		<!-- Add selectors for each group name -->
		<!-- Basically when that group name is encountered, we'll execute the instructions inside the selector -->
		<AddSelector Pattern="^Terra$" Exclusive="true">
			<!-- Each zone needs to Output to a Zone so it can be included in the k-d tree -->
			<AddOutputZone Name="Terra"/>
			
			<!-- Use those instructions we defined above -->
			<ExecuteInstructions Name="Zone"/>
		</AddSelector>
		
		<AddSelector Pattern="^Zone001$" Exclusive="true">
			<AddOutputZone Name="Zone001"/>
			<ExecuteInstructions Name="Zone"/>
		</AddSelector>
		
		<AddSelector Pattern="^Level$" Exclusive="true">
			<!-- Since this group just contains locators, we can output to the P3D file directly -->
			<AddOutputPure3DFile Name="Level"/>
			
			<!-- As well as use more specific instructions -->
			<ExecuteInstructions Name="Locators2"/>
		</AddSelector>
	</SketchUpModelOutput>

Step 8: Borrowing from the original game

Now is where those P3D files you inputted earlier come in. You're going to want to extract a few things from them to place into your map's files.

	<!-- "EnvMap.bmp" is being copied from Input "L1_TERRA" P3D into our new Output "Terra" P3D file so car reflections work -->
	<!-- This is placed at the start of the Terra file with Start="true" -->
	<Pure3DFileChunksOutput OutputPure3DFile="Terra" InputPure3DFile="L1_Terra" Type="Texture" Name="EnvMap.bmp" Start="true"/>

	<!-- Input Road Arrow Anims -->
	<!-- This is REQUIRED for missions to work (though our map doesn't have any roads so they won't work yet -->
	<!-- This is mainly here for the next tutorial that gets into adding Roads -->
	<!-- These need to be placed after any Intersections in the Terra file so you need to specify AfterIntersections="true" -->
	<!-- Lastly, it is crucial that this is after your SketchUpModelOutput element -->
	<Pure3DFileChunksOutput OutputPure3DFile="Terra" InputPure3DFile="L1_Terra" Type="Anim" Name="darrow" AfterIntersections="true"/>
	<Pure3DFileChunksOutput OutputPure3DFile="Terra" InputPure3DFile="L1_Terra" Type="Anim" Name="warrow" AfterIntersections="true"/>

	<!-- "coinShape_000" is being copied from the Input "L1_Level" P3D to the new Output "Level" P3D -->
	<!-- Since this is just a mesh, you can really put it wherever you want as long as level.mfk loads it -->
	<Pure3DFileChunksOutput InputPure3DFile="Level" OutputPure3DFile="L1_Level" Type="Mesh" Name="coinShape_000"/>

Step 9: Build and check it out ingame

Now it's time to run Built.bat again to see if it works ingame.

If you've done everything right, the map should successfully build and look something like this.

1S2DuNtTe65L3cdR-MBTut001_Ingame.png

You're done!

That's it for this tutorial. If you'd like, you can download a completed ZIP of the mod created in this tutorial from the sidebar of this page (Tutorial 001 Complete.zip).

Up Next: Tutorial 2: Adding Roads

Map Building Tutorials

Tutorial 2: Adding Roads

Introduction

This tutorial will guide you through expanding the map created in Tutorial 1: Making a Basic Map with new Road intersects as well as adding a Road Network on top of them. It will also cover making a new HUD map that contains your new road meshes.

A road network is the series of interconnected Roads and Intersections that guide traffic and AI cars through the world.

Prerequisites

You will need the following things to accomplish the steps in this tutorial:

  • The Simpsons: Hit & Run for PC
  • Lucas' Simpsons Hit & Run Mod Launcher
  • Lucas' Simpsons Hit & Run Model Builder
  • SketchUp Make 2017
    • Knowledge of how to use SketchUp in general will help as well as these tutorials may not go into very much detail about the specifics of how to use it.
  • A Text Editor, we recommend Notepad++.
  • The map created in Tutorial 1: Making a Basic Map

Part 1: The SketchUp File

Step 1: Expanding the map

In Tutorial 1, you created a small square. This doesn't really have any space for your Road network so the first thing you'll want to do is expand the map a bit.

First focus the "Zone001" group. Then you should add some 12 meter wide rectangles to each side of the map and some 12x12 squares to each corner. It would also be good to make some Materials and color them differently so they can be told apart.