WorldLoader Plugin Documentation

WorldLoader Plugin

Load Real life Cities into your game!

Features:

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

Get the plugin here: WorldLoader

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

Openstreetmaps coordinates

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.

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.

WorldLoader > Home

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.

image_2024-10-08_192402828

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 - Properties Module

Advanced Ui

if properties from the Properties Menu aren’t enough, you can use custom meshes/textures and set properties in the WayProperties module. Basic knowledge of Luau helps!

To Start, tick the checkbox blue and click the two buttons to get new folders. WorldLoader Modules folder spawns in ServerScriptService, WorldLoader Assets in ReplicatedStorage.

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.

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.

How WorldLoader works

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

  1. Get tags of an object (same as the tags on Openstreetmaps website)
  2. Goes to WayProperties and look for the first table that has a matching tag.
  3. If it finds a disabled = true variable, it stops searching and doesn’t generate
  4. If it finds an operation variable, it generates the way with the properties inside the current table
  5. 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
  6. 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):

  1. First found tag is highway with a value residential
  2. 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)
  3. 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

Below is a table of properties for each operation:

Operation Explainer
way model of parts from a list of positions
area model of wedges filling a closed list of positions (works only with Openstreetmaps ways, no relations or multipolygonal relations )
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 a closed list 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)

rail dictionary snippet

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 WorldLoader Assets > Meshes and write its name here
meshpart string Used for ballast, place a mesh inside WorldLoader Assets > MeshParts and write its name here
texture string Used for track tie textures, place a texture inside WorldLoader 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

Errors

When WorldLoader detects something you have written is not correct, an error pops up in its own window. Here are some of the errors:

  1. When you input a property in the wrong format. The error will say what property (color) needs fixing, in what table (ballast) it is and what it should really be (Color3)
    image_2024-10-08_185316311
    image_2024-10-08_185410037

  2. When an asset is missing from the WorldLoader Assets folder, As seen in the picture, theres no “Ballast” found in the folder Meshparts
    image_2024-10-08_185830029
    image_2024-10-08_185849504

3 Likes