WorldLoader Plugin Documentation

goodbadred · October 8, 2024, 6:45pm

WorldLoader Plugin

Load Real life Cities into your game!

Features:

Custom World Scale
Terrain and no terrain option
Configurable Properties (color, material, scale, …)
Generation of Areas (parks, fields, pitches, …)
Ro scale compatibility
History - previously used coordinates save

Get the plugin here: WorldLoader

Also available on Github

All data is provided by Openstreetmaps

Any problems with the plugin, bugs, feeback or help needed? Join my Discord Server

Getting Started

Read the guide bellow or watch a Youtube Tutorial

First, you need to get coordinates of your place. Go to Openstreetmaps and find a place you’d like to import. Right click on the map, click “Show address” and copy the coordinates (image top left). These coordinates will be the center of the loaded area.

Alternatively, you can get your coordinates from Google maps, thats how i did it in the Youtube tutorial.

Now, go to Studio and select a new part. This part will serve as the area of the loaded city. Bigger the part, bigger the city! Coordinates are set at 0,0 in workspace, if you want the area to load around the coordinates, move the part also to 0,0.

Next, open the plugin. This is how the Home tab of the plugin looks, input your copied coordinates in the first Textbox¹. Default Scale² is 1, meaning real life scale, being 1 meter = 3.57 studs. History button opens a menu of previously used coordinates and scales. Next step is to download³ the data, and then hit Generate⁴.

If you want to generate an area beside it, but for it to connect with the generated previously, don’t change any coordinates, just move the part and generate.

Still lost? Watch a Youtube Tutorial

Tips

Some buildings with more complex shapes can generate inside one big building with the land area of the complex shape, but height of the highest point of the complex building. Sadly, there is nothing I can do about this, but you can delete these incorrect buildings yourself, buildings with correct height will be under it.

Maximum area you can generate depends on the size of the part you have selected, so max 2048 by 2048 studs. BUT you can generate larger areas by generating multiple times! After generating the first time, move your part, and without changing scale or coordinates, download data and generate again.

Editing Properties

To edit some of the properties of Buildings, Roads and Rails, open the PROPERTIES tab.

First, you can edit Generation Rules (image top).

Replace Duplicates replaces all found duplicate objects when Generating, otherwise these objects get skipped (reducing generation time). This is useful when you changed a few properties and want to regenerate the area without deleting stuff from Workspace.
Ro-Scale generates all rails with same hitboxes as Default Ro-Scale rails.
Ro-Scale Ties overrides set tie dimension with default Ro Scale tie dimensions
Ro-Scale Ballast overrides set tie dimension with default Ro Scale ballast dimensions
Track Handles generates Track Handles for rail, used in Ro Scale to easily connect rails
Areas generates colored areas from wedges according to Openstreetmaps, for example, when there is a park on Openstreetmaps, there will be a model made from wedges marking the space.

Next, editing properties. All values are in meters! Most of these are self explanatory, I’m only going to explain the more tricky ones.

Buildings > Default Height: Openstreetmaps don’t provide height for all buildings. If height isn’t found, this value will be used.
Buildings > Height per floor: If height is provided, its normally in the number of floors. This value dictates how many meters per floor the building generates with
Rails > Rail Gauge: In real life, rails have different gauges, which is are distances between two rails. Deafult value is 1.435, Standard gauge, used in Europe and North America
3D Ties: When enabled, ties are going to be parts and able to have changed color and material, if disabled then a texture will be used for ties (more performant in game)

(Advanced) Forking and editing all properties

If properties from the Properties Menu aren’t enough, you can edit a module that describes how each type of object is generated. Basic knowledge of Luau helps!

For this, get the latest version of the plugin as a file from github (releases) and place it into your Studi plugins folder

You can edit all properties of objects by writing your own module that stores them. In EditableModules, you’ll find an already written module that the plugin uses as default for all properties. Down bellow you’ll learn how to edit it. Name of this module does not matter, only its location.

How WorldLoader works

For you to be able to perform more advanced stuff with the plugin, I am going to briefly explain the innerworking of it.

Go to Openstreetmaps and locate this Query button. Now click on something on the map.

When you click somewhere, a circle will apear around your mouse, and a list of all items inside that circle. Click on an item in the Nearby Features list and a list of tags (image above) will appear.

OSM (Openstreetmaps) use 3 types of objects: nodes, ways and relations. Nodes are points on the map with coordinates and Ways are a group of nodes with certain tags. In our case, only Ways are important.

Here is a snippet from WayProperties. How WorldLoader works is:

Gets tags of an object (same as the tags on Openstreetmaps website)
Goes to WayProperties and looks for the first table that has a matching tag.
If it finds a disabled = true variable, it stops searching and doesn’t generate
If it finds an operation variable, it generates the way with the properties inside the current table
If 3. or 4. weren’t found, it looks up a value of the tag and tries to find a table with that key inside the current table. If the current table is alredy a value of a tag, it searches with a new randomly picked tag from the way
If it finds the value as a table, it continues with 3., 4. and 5., else it tries to find a table named nil inside the current table and execute 4. or 5. in it

In the case of Way: Mateja Bela (image with example tags):

First found tag is highway with a value residential
Inside highway table, it finds a residential table (If, for example, it didn’t find a residential table, it would select the nil table and go from there)
Inside the residential table, it find an operations variable, so it now knows that it will use variables inside this table as properties.

Operations

There are 5 types of operations that WorldLoader uses to generate Ways, these are:

way
area (experimental)
area/way
building
rail

A lot of object in OSM use relations or simular, but WorldLoader only supports operations mentioned above.

Below is a table of properties for each operation, closed array means the positions in it are used as an outline for an object, they create a polygon:

Operation	Explainer
way	model of parts from an array of positions
area	model of wedges filling a closed array of positions
area/way	WorldLoader checks if there is an `area` tag inside the Way, if its found then the operation is set to `area`, else its set to `way`
building	model of wedges filling an array of positions but with properties like heightPerFloor and deafultHeight
rail	model of tracks. Each track has a ballast meshpart, two mesh rails and a tie texture or tie parts

Operation	Properties
way	parent, color, material, height, width
area	parent, color, material, height
area/way	parent, color, material, height, width
building	parent, color, material, heightPerFloor, deafultHeight
rail	parent, gauge, ballast = {width, height, meshpart, color, material}, ties = {ties3D, texture, color, material, transparency}, rails = {mesh, color, material}

For way, WorldLoader checks if it has lanes as a tag and widens or narrows the way (expected to be a road)

Here you can see that the rail table has more tables (ballast, ties, rails) inside of it. Inside of them, there are also properties that you can edit. WorldLoader knows these aren’t just more another tags because there is an operation variable inside this table.

Below is a table explaining each property:

Property	Type	Explainer
parent	string	What folder (inside a generated folder named “World” inside workspace) is going to be the parent
disabled	boolean	if true, object doesn’t get generated
operation	string	Operations
color	Color3	Color of the object
material	Enum	Material of the object
transparency	number	How transparent the object is
height	number	Y Size of object (meters)
width	number	X Size of object (meters)
deafultHeight	number	Openstreetmaps don’t provide height for all buildings. If height isn’t found, this value will be used (meters)
heightPerFloor	number	If height is provided, its normally a number of floors. This value dictates how many meters per floor the building generates with
gauge	number	How far are rails from each other, wikipedia
mesh	string	Used for rail meshes, place a mesh inside `Objects > Assets > Meshes` and write its name here
meshpart	string	Used for ballast, place a mesh inside `Objects > Assets > MeshParts` and write its name here
texture	string	Used for track tie textures, place a texture inside `Objects > Assets > Textures` and write its name here
ties3D	boolean	If ties should be generated as parts and not textures, when enabled, they also have color and material properties

WARNING: I do NOT recommend editing mesh, meshpart or texture properties as I did not code this plugin to be able to use custom meshes or textures for objects. Still, here they are:

There isn’t really any error checking for the module, so you’ll have to figure out any errors yourself, good luck! :D

Again, if any questions arise, feel free to ask them in my Discord