Heightmaster - A way to convert heightmaps and texturemaps into terrain

Some time ago in the past, I had created a very rudimentary heightmap importer plugin, however, it never really produced any kind of terrain that I would deem ‘good’. As such, I never released it to the public, but after some time rewriting the whole thing, I’ve decided now would be a good time to release it publicly.

Introducing Heightmaster, a way to convert heightmaps with a texture map into terrain. It allows you to generate a heightmap in a program like World Machine, along with a texture map, and then convert that into terrain. Keep in mind that each pixel within the heightmap will create a voxel of 4^3 studs, so a heightmap which is 512x512 pixels, will create a terrain map that is roughly 2048x2048 studs.

It is important to note, that in order to use the heightmap converter I have provided, you will need to have Java installed. I have also included the programs source code as well if you would like to compile it yourself, but if you would like to create your own application for converting the heightmaps, feel free. The Heightmaster.jar program isn’t polished or well made since I have little experience with Java.


You can download the Roblox plugin here.

In order to download the Heightmaster.jar program, you will need to head to the GitHub repository here. The GitHub page also goes over what each property of the plugin does.

How to use

Say we generate these two textures from a World Machine project.



We can then run the Heightmaster.jar program to convert the two textures into a single Lua file which Studio can run.

From here, Open Studio (Preferably onto a new place), an click Run Script (Which you can find under Model > Advanced > Run Script). I will probably change how this method is done in the future.

After you have run the script, you can begin opening the Heightmaster plugin, and edit the settings to fit your needs (I will explain what each setting does down below). You are also able to press the ‘Visualise’ button in order to see a basic idea of how the finished terrain may look like. Once everything is set up, just hit ‘Generate’ to begin the terrain’s generation. Keep in mind, terrain generation may take some time (Depending on how large the original heightmap was).

Plugin Properties

Here I will go over what each property in the plugin does, so you can get the best idea of how to utilise it.

Terrain Settings

  • Terrain Origin - This Vector3 value is the centre and base of the generated terrain.

  • Terrain Scale - This is a value between 0 - 250 (However if you enter your value in the textbox, you can go higher), which stretches the terrain to be shorter or taller depending on the value.

  • Terrain Smooth Depth - This is how far down will the terrain occupancy be ‘smoothed’ rather than having an occupancy of 1.

  • Remove Level 0 - If this is active, then any terrain that has a height of 0 in the heightmap will not generate. (This could be useful if you would like to generate floating islands or something).

  • Invert Terrain - Inverts the terrain (generates downwards from the origin), this could be used for making caves?

  • Optimize Terrain - This rounds the voxel occupancies to help reduce the file size of the terrain, might need to improve it later.

  • Remove Excess Terrain - This removes terrain which is under the surface which would otherwise be filled up.


  • Default Material - This is the material that will be used if the material mode is set to ‘Disabled’.

  • Material Mode - This is the mode of how the terrain’s material is found from the texture map (Depending on what colour the current texture is, will produce a different material).

    • Disabled - This is the option to pick if you do not want to generate from a texture map, this is will instead just use the default material.

    • Roblox Default - This will get the material from whatever is set under Workspace > Terrain > MaterialColors.

    • Enhanced - This option uses the average colour from the default texture of the material (This might be more accurate).

    • Custom - This option allows you to choose your own custom colours to be assigned to the materials.

Subsurface Material Settings

The subsurface material is a specific material that is under the surface of the terrain (By default, 75% of the terrain will be rock).

  • Use Subsurface Material - This is a bool to toggle subsurface material.

  • Subsurface Material - This is the material that will be generated under the surface.

  • Subsurface Height - This is how far up the terrain will generate.


  • Enable Water - Toggle the generation of water.

  • Water Occupancy - The occupancy of the water voxels.

  • Water Height - The height at which water will generate (0 - 255, to match the heightmap).

  • Water Size - This is how large the water will generate (How much bigger than the terrain generated from the heightmap).

  • Use Subwater Material - This will use a specific material to be generated if the terrain is below the water height instead of just using the texture.

  • Subwater Material - The material that will be generated under the water height.

  • Generate Seabed - This option will generate a layer of material under the base of the terrain in order to cap the water if the water size is greater than 1. This will use the Subwater Material value.

  • Seabed Depth - How far down will the seabed material generate.


The beach allows you to set a material that will generate above and below the water height.

  • Enable Beach - Allows you to toggle if the beach will be generated or not.

  • Beach Height - How far above the water height will the beach generate.

  • Beach Depth - How far below the water height will the beach generate.

  • Beach Material - The material that will be used in the beach.

Allowed Materials

This lets you enable or disable specific materials for use in the material mode generation.

Custom Materials

These settings let you define custom colours for the materials. This is used in the custom material mode.

Showcase of generated terrains



My mind is unable to even comprehend the possibilties and potential this has. Thanks a million!

Requesting immediate promotion


Pretty wicked, I’ll try it out if I ever need specially shaped terrain like this.

1 Like

This is incredible! For years I’ve played Cities : Skylines and they used height-maps to convert to terrain. I’ve been thinking of ways to do this in Roblox and I am so happy that you’ve created this, great job man!

1 Like

This is CRAZY, thank you for this!

1 Like

I’ve been wanting one of these since 4 years ago :joy:

Will make sure to check this out :smiley:

1 Like

This. Is. Epic.

1 Like

This is definitely useful

1 Like

I have released an update for the plugin which adds some features that I wanted to add a while ago - these being;

  • A toggle to invert the terrain, which could be useful for making caves?

  • A toggle to ‘optimize’ the terrain. This should reduce the occupancy size of each voxel.

  • Changed the colour that the visualiser uses to better fit the actual material colour for the terrain (Before it would just use the colour from the heightmap, which might not give the best idea of what the terrain will look like).

  • A toggle to remove excess terrain (Rather than generating a large chunk of terrain that completely filled, it will generate from the lowest point in the heightmap, hopefully reducing memory size of the terrain). This should hopefully keep the same terrain on the surface.

  • A slider to change the occupancy of the water. (The lower the occupancy, the smoother the transition between land and water will be).

I had tried to implement a method to import heightmaps directly through the plugin using the StudioService:PromptImportFile() and using a Lua PNG DEFLATE method, however, I was having a lot of trouble with it, so I have decided to scrap that for the time being.


mind if i knew what version of java the tool requires to run? running on java 8u201 and java 10u1 runs but exports an empty lua. this occured after the first few times ran and exported incomplete files

Hm, that seems strange. I can’t check right at this moment in time, but I will get back to you on that.


I’m having trouble replicating your issue.
Are you using windows? I know that some users have had some issue running the program on a mac.

yep, windows 10. could it be because all i have is 64 bit java?

Is a heightmap texture required, I’m using terrain party and it doesn’t generate a texture, only a heightmap.

Nope a texture is not necessary, you can just assign the heightmap image as the texture when using the application.

You will have to set the Material Mode to Disabled in the plugin however, otherwise things may get a bit funky, but you can choose a smooth terrain material in the Default Material box.

Alright, thanks. This is a really good plugin!

I have followed all the instructions to make it work, but it wont work for me, please help

Could you elaborate a bit on what you’re having trouble with? Alternatively if you send me a DM, I can go into more specifics on how to use the plugin.

I followed everything, and it still says “Please load a heightmap”

The heightmaster.jar program doesn’t work for me. I can’t open the program

Bookmarked! This is even better than my tutorial!