Ultimate Doom Builder with scripting capabilities (feedback wanted)

[boris]

What is this?

This is an experimental version of UDB with scripting capabilities. It allows the users to write and run scripts that can do pretty much anything to the currently opened map, like adding or modifying geometry and things.
This feature has been brewing for quite some time, so this version can be regarded as a release candidate. That means it will be merged into the master branch soon if no (big) flaws are found.

 

To find such potential flaws I need feedback on how usable it is, what's working good, what's not, if there's anything nonsensical in the API, or even the docs (see below).

 

Where can I get it?

Here: https://devbuilds.drdteam.org/ultimatedoombuilder/UDBScript-Test-4.7z

Make sure to unpack it in a clean folder. Do not overwrite your existing UDB installation with this!

 

What language is used to write scripts?

JavaScript.

 

What do scripts look like?

There are a couple examples included, you can also check them out here: https://github.com/jewalky/UltimateDoomBuilder/tree/udbscript/Build/UDBScript/Scripts/Examples

Here's what the example script to create a door looks like:

 

Spoiler

 

`#name Make Door`;

`#description Creates a door from a selected sector. Functionality is the same as the built-in "make door" action.`;

`#scriptoptions

doortexture {
    description = "Door texture";
    default = "BIGDOOR2";
    type = 6;
}

doortrack {
    description = "Door track texture";
    default = "DOORTRAK";
    type = 6;
}

ceilingtexture {
    description = "Door ceiling texture";
    default = "FLAT20";
    type = 7;
}

`;

let sectors = Map.getSelectedSectors();

if(sectors.length == 0)
    die('You need to select at least one sector!');

sectors.forEach(s => {
    s.ceilingHeight = s.floorHeight;
    s.ceilingTexture = ScriptOptions.ceilingtexture;

    s.getSidedefs().forEach(sd => {
        if(sd.other == null) // 1-sided lines
        {
            sd.middleTexture = ScriptOptions.doortrack;

            if(Map.isUDMF)
                sd.line.flags.dontpegbottom = true;
            else
                sd.line.flags['16'] = true;
        }
        else // 2-sided lines
        {
            // If the sidedef is on the front of the linedef we need to flip the linedef
            // so that the line can be activated properly
            if(sd.isFront)
                sd.line.flip();

            sd.other.upperTexture = ScriptOptions.doortexture;

            // Set the action
            if(Map.isDoom)
                sd.line.action = 1;
            else
            {
                sd.line.action = 12;
                sd.line.args[0] = 0; // Tag
                sd.line.args[1] = 16; // Speed
                sd.line.args[2] = 150; // Close delay
                sd.line.args[3] = 0; // Light tag
                
                if(Map.isHexen)
                {
                    sd.line.activate = 1024; // Player presses use
                    sd.line.flags['512'] = true; // Can be used repeatedly
                    sd.line.flags['8192'] = true; // Can be activated by monsters
                }
                else // UDMF
                {
                    sd.line.flags.repeatspecial = true;
                    sd.line.flags.playeruse = true;
                    sd.line.flags.monsteruse = true;
                }
            }
        }
    });
});

 

 

 

 

Is there any documentation?

Yes! For the time being you can find it here: https://biwa.github.io/udbscript-docs/
Make sure to check out the "Getting started" section which has a detailed explanation of how everything works.

 

Is this the same as DBX's scripting?

No. DBX uses Lua for its scripting, so those scripts will not work with UDBScript. But since both DBX's scripting and UDBScript are exposing the same underlying structures it shouldn't be too hard to convert scripts from one editor to the other.

Edited October 16, 2021 by boris

[Nash]

Have been using it

Can confirm it's good

[boris]

For the 3 people that care: UDBScript was merged into the master UDB branch, a new version was released just now. Up-to-date docs are here: https://biwa.github.io/udbscript-docs/

 

For those who don't know, UDBScript lets you write JavaScript scripts to programmatically modify the currently opened map (like DBX's Lua plugin, just different).

[Nash]

UDBScript is a game changer.
 

Now just gonna wait for someone to write an Oblige-style map generator in UDBScript. :P

[HavoX]

SW-EET