Gorescript Level Editor Help

back to top

Overview

The Gorescript Level Editor allows you to create custom levels for Gorescript. You can:

  • Create entirely new levels and share them on Steam Workshop
  • Add monsters, weapons, powerups and explosive barrels
  • Add switches, trap doors and elevators
  • Modify lighting
  • Script various parts of the level using Lua

The editor is a separate app from the game itself, built as a JavaScript desktop application using GitHub's Electron.

Mouse and keyboard controls

Here's a listing of the primary mouse and keyboard controls for the editor.

Mouse:

  • Left-click and hold to select/draw (depending on the currently selected layer and mode)
  • Right-click and hold to move around

Keyboard:

  • Hold left CTRL to append/deselect an element when multi-selecting
  • Hold left SHIFT when drawing segments to draw them at 90 degree angles

Tutorial videos

The level editor might seem a bit scary at first, so we prepared some videos showing you how to build a simple Gorescript level. Since there's never enough E1M1 tribute levels out there, here's our take on the subject.

Part 1 - Setup, Segments and Sectors

In this part we go over installing the level editor from Steam and making your first room.

Levels in Gorescript are 2.5D, meaning you can never have one room over another one. Similarly, you can't build actual bridges (the type where you can walk above and below them). Think of a level as a blueprint for one single floor of a house.

The usual steps for building a room are:

  1. Draw polygons using segments
  2. Go through each polygon and convert it to a sector
  3. Go through each sector and modify properties such as floor height, floor-ceiling distance, light level, light color, etc.
  4. Mark certain sectors as doors
  5. Add lights

A few gotchas:

  • You need to have at least two adjacent sectors, otherwise you'll get the "sector has no corresponding region" error
  • Make sure to click "Regenerate sides" (Segment layer menu) after creating or modifying sectors, otherwise the sectors won't have walls. Beware though, since "Regenerate sides" will remove all user-generated segments except those explicitly marked as switches or TV screens.
  • Make sure to set the player start position to somewhere within a sector, otherwise you'll start in outer space

In case you were wondering, the "Gorescript green" is "rbg(192, 250, 192)".

After you have at least one room set up, click the "Save" button in the menu. Then click the "Play map" button to run it.

The custom levels you create via the level editor are saved in the "Gorescript/assets/custom-maps" folder, with a new folder created for each custom level.

For any level the resulting folder structure is (using the "e1m1_tribute" level as an example):

  • Gorescript/assets/custom-maps/
    • e1m1_tribute/
      • map.json
        • (Required) The level itself (generated automatically, do not modify except by using the level editor)
      • metadata.txt
        • (Required) Level metadata for Steam Workshop (also generated automatically, do not modify except by using the level editor)
      • e1m1_tribute.png
        • (Optional) The thumbnail image for Steam Workshop (can be either .png or .jpg, not added by the level editor, you can add/modify this manually)
      • script.lua
        • (Optional) The Lua script for the level (required if the "Has script" checkbox is checked, also not added by the level editor, you can add/modify this manually)

Part 2 - Stairs, Windows and Outdoor Areas

In this video we go over a few more advanced topics:

  • Stairs are adjacent sectors with increasing or decreasing floor heights. The floor height difference between stairs should be no more than 4, to allow the player to climb them without needing to use anti-grav boots.
  • Windows are usually sectors with higher floor height and smaller floor-ceiling distance compared to adjacent sectors. The floor height difference between the window and the adjacent sectors is usually 8 or more, to prevent the player from climbing on top of it.
  • Outdoor areas are sectors with the "Ceiling" checkbox unchecked. The floor-ceiling distance should be 64 or more to prevent the player from jumping over the walls and into outer space.

Part 3 - Weapons, Monsters and Powerups

In this video we go over weapons, monsters and powerups which are all added via the Entity layer menu. For a more thorough listing, see the Entity part of the Reference section.

Make sure to click "Compute Y for selected entities" at least for each newly added entity, or when the underlying sector has changed height. Otherwise the entities might end up floating high up in the air or be buried inside level geometry.

Part 4 - Outdoor Areas Revisited

In this video we go over outdoor areas again, this time in more detail. The outdoor area shown in Part 2 is the "unreachable" kind. This video shows how to make "walkable" outdoor areas.

A key part of making "walkable" outdoor areas is the "Ceiling thickness" sector parameter. This parameter is used on the sectors located immediately next to sectors with the "Ceiling" checkbox unchecked to specify the height of the side panels (created automatically when clicking "Regenerate sides" in the Segment layer menu.

Part 5 - Elevators, Switches and Scripting

In this video we go over the final touches. First off, the red "end level" ball is an entity called "letter" (don't ask), similar to weapons and powerups.

Secondly, we illustrate two advanced topics:

  • Elevators are sectors, similar to doors, that allow you to move up and down on top of them. Elevators are usually scripted.
  • Switches are special segments that are drawn on top of existing wall segments and render an on/off switch. Switches are always scripted since they don't do anything by themselves.

Thirdly, we go over scripting. For a more thorough listing, see the Scripting part of the Reference section.

Part 6 - Publishing to Steam Workshop

This video shows how to publish a level to Steam Workshop. Publishing is done via the level editor and will upload the contents of the level folder to Steam Workshop.

Once a level is successfully published, it will be assigned a workshop ID. Subsequent publishing will in fact edit the existing Steam Workshop item associated with the level.

If for any reason you want to create a new item instead of updating the existing one, make sure to check the "Publish as new item" checkbox when publishing.

To be able to access a custom level in Gorescript, you must be subscribed in Steam Workshop to that level. Once subscribed, if the level doesn't show up ingame in the "Custom levels" menu, restarting Steam should fix it.

Reference

This section is meant to serve as a reference for level editor functionality.

Layers

Each level is composed of 5 layers:

  • Segment. Lines describing walls. The primary way of adding geometry to a level. Can be either walls, side panels, switches or TV screens. Walls and side panels are auto-generated (via the "Regenerate sides" button) while switches and TV screens are user-drawn.
  • Sector. Polygons describing floors and ceilings, doors and elevators. Created by converting segments to sectors.
  • Entity. Points describing monster and powerup placement.
  • Zone. Rectangles used as triggers in the level script.
  • Light. Points describing light placement and color.

Following is a list of properties for each layer.

Segment

  • Bottom Y. Integer. The bottom Y position used when rendering the segment.
  • Top Y. Integer. The top Y position used when rendering the segment. Must be higher than Bottom Y.
  • TV screen. Boolean. Marks the segment as a TV screen, normally used as a decal over existing wall segments.
  • Texture. String. Only visible if the segment is marked as a TV screen. Default value: "wall". Possible values include:
    • exit
    • strafe_run
    • why
    • under_construction
  • Switch. Boolean. Marks the segment as a switch, used in scripting. If checked, Top Y is unused.

Sector

  • Floor height. Integer. The height of the floor part of the sector.
  • Ceiling. Boolean. Specifies if the sector has a ceiling.
  • Floor-ceiling dist.. Positive integer. The distance between floor and ceiling (also must be defined for sectors without ceiling).
  • Ceiling thickness. Positive integer. The height of the side panel generated when a sector with ceiling is located next to a sector without ceiling.
  • Door. Boolean. Marks the sector as a door.
    • Door max height. Positive integer. Only visible when the sector is marked as a door. Specifies how high the door should raise when opening. Should be at least 24 to allow monsters to pass through.
    • Key. Selection. Only visible when the sector is marked as a door. Specifies if the door needs a certain key (red, blue) to open.
  • Elevator. Boolean. Marks the sector as an elevator.
    • Elevator max height. Positive integer. Only visible when the sector is marked as an elevator. Used to determine the bottom Y position of the elevator.
  • Use vertex colors. Boolean. Only visible when the sector is marked as a door or an elevator. Specifies if the resulting door/elevator should use a texture (unchecked) or be painted in the same color as defined by the sector "Light color" + "Light level" properties (checked). Used for hidden doors/elevators.
  • Floor texture. String. Only visible when the sector is marked as an elevator and "Use vertex colors" is unchecked. See Textures below for a list of possible values.
  • Ceiling texture. String. Only visible when the sector is marked as a door and "Use vertex colors" is unchecked. See Textures below for a list of possible values.
  • Side texture. String. Only visible when the sector is marked as a door or an elevator and "Use vertex colors" is unchecked. See Textures below for a list of possible values.
  • Textures. Used in Floor texture, Ceiling texture and Side texture.
    • cyan_wall
    • blue_metal
    • dark_blue_metal
    • white
    • wall
    • metal
    • red
    • red_metal
    • blue
    • cyan
    • brown
  • Teleport In ID. Positive integer. Only visible if the sector is not marked as a door or an elevator. Marks the sector as a teleportion pad. When entering the sector, the player is teleported to the sector marked with the same ID on "Teleport Out ID". Sectors can either be "Teleport In" or "Teleport Out", not both.
  • Teleport Out ID. Positive integer. Only visible if the sector is not marked as a door or an elevator. Marks the sector as the exit area of a teleportion pad. Must match the ID of another sector's "Teleport In ID".
  • Light level. Positive integer between 1 and 10.
  • Light color. Color.

Entity

Entity types:

  • Powerups
    • redkey. The red key.
    • bluekey. The blue key.
    • ammo. Ammo pickup.
    • medkit. Health pickup.
    • powerup. Random powerup connected to a loot table. See Loot table ID below for a list of possible values.
    • armor. Armor shard pickup.
    • letter. Red ball which ends the level.
  • Monsters
    • nom. Big red thing that wants to eat you.
    • eye. Blue thing that wants to shoot you.
    • hydra. Big green thing that wants to shoot you three times.
    • boss1. Huge four-eyed blue thing that shoots rockets in all directions.
    • boss2. Huge red thing that wants to eat you.
  • Scene props
    • barrel. Explosive barrel.

Properties:

  • Y. Integer. The Y axis position to place the entity at. Usually set indirectly by clicking "Compute Y for selected entities".
  • Rotation (deg). Integer. Only visible for monsters. Specifies the initial rotation (in degrees) of the monster.
  • Static. Boolean. Only applicable for powerups. If checked, the powerup doesn't move up and down if placed on top of an elevator.
  • Loot table ID. Positive integer. Must be between 1 and 6. Only visible for powerups of the "powerup" variety. See Entity types above. Possible values include:
    1. Sledgehammer
    2. Double Shotgun
    3. Randomly: HyperBlaster, Rocket Launcher, Railgun, Health Cube, Breastplate, Nightmare Contraption, Bloodlust Goggles.
    4. Randomly: same values as 3. plus Anti-Grav Boots.
    5. Devastator
    6. Rocket Enhancer

Zone

  • Name. String. Required.

Light

  • Y Offset. Integer. Lights are by default placed in the middle of the floor and ceiling Ys. This property offsets that Y position.
  • Light color. Color.

Scripting

A Lua scriptfile can be added to a map by creating a "script.lua" file in the map folder and checking the "Has script" checkbox in the Map menu.

The following functions will be called if the script provides an implementation:

  • init(). Called every time you respawn.
  • onZoneEnter(zone: Zone). Called every time you enter a zone (as defined in the Zone layer).
  • onZoneLeave(zone: Zone). Called every time you leave a zone.
  • onPowerupPickup(powerup: Powerup). Called every time you pick up a powerup.
  • onPlayerOpenDoor(door: Door). Called every time you open a door.
  • onSwitchStateChange(switch: Switch). Called every time you use a switch.

Exposed classes:

  • Door
    • getId() : number
    • setAutomatic(value: boolean) : void
    • setSpeed(value: number) : void
    • open() : void
    • close() : void
    • setCrusher(value: boolean) : void
  • Elevator
    • getId() : number
    • getDownY() : number
    • setDownY() : number
    • getUpY() : number
    • setUpY() : number
    • setAutomatic(value: boolean) : void
    • setSpeed(value: number) : void
    • setPositionUp() : void
    • setPositionDown() : void
    • goUp() : void
    • goDown() : void
  • Powerup
    • getId() : number
  • Switch
    • getId() : number
    • isOn() : boolean
    • block() : void
  • Monster
    • getId() : number
    • awaken() : void
    • makeScripted() : void
  • Zone
    • name : string

Exposed globals:

  • doors: table of Door, key is door ID
  • elevators: table of Elevator, key is elevator ID
  • powerups: table of Powerup, key is powerup ID
  • switches: table of Switch, key is switch ID
  • monsters: table of Monster, key is monster ID

Limitations

  • Only individual custom levels can be created and published. There's no option to create and publish campaigns at this time.
  • Since only individual custom levels can be played, there's no "Permadeath" option when playing one.
  • Your inventory and all random powerups are reset every time you die and respawn.