MAPMAKER'S TOOLKIT v1.3
Page: http://www.plazmaburst2.com/?s=9&a=&m=v ... k-publish1
Map Source (opens level editor): http://www.plazmaburst2.com/level_edito ... ublish1&a=
Page: http://www.plazmaburst2.com/?s=9&a=&m=v ... k-publish1
Map Source (opens level editor): http://www.plazmaburst2.com/level_edito ... ublish1&a=
Table of Contents
1 Introduction
- 1.1 How to cheese your way through the entire PB2 campaign
- 1.2 Changelog
3 Using Toolkit
4 Mapmaker's Toolkit Manual
- 4.1 Toolkit Management
- 4.2 Basic Commands
- 4.3 Gun Manipulator
- 4.4 Level Design Tweaker
- 4.5 Variable Manipulator
1 Introduction
Mapmaker's Toolkit is not a map designed to be played - rather, it is an open-source set of tools and triggerwork designed to give greater efficiency to mapmakers in doing what they do, by injecting certain abilities of the Level Editor into the in-game environment itself.
As you can see, with Toolkit, you can tweak a map's layout and logics during playtesting. Obviously, once you decide the changes to the systems you make in-game deserve to be made permanent, you'll need to return to the level editor and actually make that triggerwork/level design manually - but you can see what you can do with these tools. They're divided into text commands and gun tools.
These features were constructed with a low performance impact on playtests, and - more importantly - utter ease of use as a mapmaker in mind. If you're asking how heavy the process of including all (or some) of these features into a map you're working on will be, don't worry - most of the commands featured above will work straight out of the box, all the triggerwork pasted into your map, and the Variable Manipulator commands - those prefixed with -vm. - take only a copy and pasting of a single trigger, and editing 3 lines of text, to have a desired variable be manipulated in-game by command.
Almost all variables used within Toolkit's internal functioning are prefixed with "mmtk.", so there won't be any collisions with variables used by the map you want all this in, with a few exceptions that slipped through due to my own negligence: these unprefixed variables are Text, CText, UserSlot, and PlayerSlot.
All this is functional in both multiplayer and singleplayer, but a likely elephant in the room is that chatting isn't permitted by default in singleplayer, because that was originally implemented into the game for cheats for the singleplayer campaign. You'll need to beat said campaign in order to gain access to that, and then set your username as "root" without the quote marks when you play. Fear not, you can make the process painless if necessary:
1.1 How to cheese your way through the entire PB2 campaign
Spoiler: Show More
1.2 Changelog
Spoiler: Show More
2 Setup & Essential Concepts
"So, how could a mapmaker such as myself utilize Mapmaker's Toolkit?" Good question. You will need to copy and paste the appropriate objects, or plug them, from the map's source into your own map in order to enable these features, and arrange them as instructed. Toolkit is composed of 2 major parts:
Spoiler: Show More
With the foundation in place, the programming for the features themselves are held in source as seperate pieces of triggerwork, organized modularly into suites of related tools.
Spoiler: Show More
All preparation of triggerwork that is required before a feature of Toolkit can be used is collectively referred to as setup. Each suite requires a different amount of setup before use; out of those within this post the Level Design Tweaker suite requires the least and Variable Manipulator the greatest. The other aspect of suites to watch out for is plug compatibility. No tools featured in this thread will require concern about this, but future ones may. A suite's plug compatibility indicates what map elements a suite may conflict with if it is plugged into a map that has them. They'll be listed in the suite's manual section if it ever comes up.
The minimum setup needed to operate Toolkit, without any other suites plugged, is needed within the toolkit logics themselves - you'll need to edit these guys right here and make the following modifications:
Spoiler: Show More
- 1. As a text command system, you will need a message reciever. You will need to set this up so that it doesn't conflict with text command systems already present in your map, and keep the variables Toolkit sets up within the trigger intact. If this won't be an issue, simply set the trigger as Message Reciever.
- 2. Config triggers like this one are found in Toolkit suites all around as well as in the logics here. They contain "settings" for the suite you're dealing with that you might want to customize. Toolkit's config contains 9 variables you can modify:
- mmtk.adminNeeded: This determines if a player must be in the Administrators list below in order to use commands and gun tools within the map. Any player can use any command if the variable is set to 0 - if its set to 1, admin will be necessary. Admin will not be necessary if Toolkit is used in Singleplayer even if this is enabled, for obvious reasons.
- mmtk.displayErrors: If set to 1, announces errors the logics encounter in the chat, usually when Toolkit detects you used a command incorrectly.
- mmtk.admin1Login, mmtk.admin2Login, ... : The names of the 4 Administrators who will be able to use Toolkit in your map if mmtk.adminNeeded is set to 1.
- mmtk.displayExecs: Only relevant to developers looking to modify Toolkit. If set to 1, announces execution of events in the chat.
- mmtk.displayIniNick: Only relevant to developers looking to modify Toolkit. If set to 1, announces the character name of the player targeted by PlayerIdentification in the chat.
- mmtk.displayReturns: Only relevant to developers looking to modify Toolkit. If set to 1, announces variables returned by functions that have been executed in the chat.
- 3. The final thing required to get everything ready. PlayerIdentification is a function composed of 4 triggers used by many Toolkit features when a tool needs to target a specific player to affect in some way. You must configure each as instructed:
Spoiler: Show More
The Toolkit logics are fully functional. Next, you will need to include one of the 4 suites available with this publication of Toolkit, in the source - your options are Basic Commands, a very general set of tools used for all sorts of simple quality-of-life playtesting improvements; Variable Manipulator, the most robust suite that allows you to manipulate any variable within the map logic with ease; Gun Manipulator, which allows you to move guns around and clone guns with any stat modifications you wish; and Level Design Tweaker, which speaks for itself.
Simply copy and paste it into the map anywhere. Unless that suite specifically states that it requires setup, all the tools within it will be ready for use. The remainder of this forum post will function as a manual for your newfound abilities, introducing each suite that currently exists, describing the setup it requires and the config it contains, and providing documentation for each command and gun tool's use and function. Take a suite in the source, read up on it, and you'll be on your way.
3 Using Toolkit
This will be a guide to interpreting the manual below so that you may learn how a specific feature works and how to use it. Many suites have features based on gun tools, as you saw in the video, that mimic functions of the level editor - they won't need explanation. The majority of the manual info focuses on commands.
One-Liners
A one-liner is a command that simply creates a desired effect when you chat its name. If you have Basic Commands plugged, you chat "-bc.bom" and an explosion occurs. Simple as that. Commands that require arguments are more interesting.
Argument Commands
Obviously, many commands will need you to enter more info into the chat than just their name to function. This is reminiscient of text commands in other games; You say "/SetHealth Me 250", you get 250 HP. Unfortunately, due to limitations in the PB2 engines, I can't replicate this. Instead, you must speak each additional piece of info required in a subsequent chat message after saying the command's name, as you saw. You type "-bc.tele", chat it, then chat "500," in a new message, then chat "-150", and you're teleported to the coordinates x 500 y -150. These commands are referred to as argument commands, and pieces of information that must be supplied through individual chats, arguments.
-bc.srd (e Value)
Toggles character swords on or off.
- (e Value)
0 - Disables swords.
1 - Enables swords.
This is how a description of a command that needs arguments is formatted in the manual. (e Value) indicates that you must chat 0 or 1 after chatting "-bc.srd" to tell the map to either disable or enable swords. The "e" denotes that it is an Enum argument: when input of an Enum argument is required from you, you chat a number to select a certain option out of a numbered list of options, as seen in the example above.
-bc.tele (n XPosition) (n YPosition)
Teleports the user to the location defined by XPosition and YPosition.
Number arguments usually have no limits to their options, instead using the numbers inputted to define much more fluid characteristics for the command. You may teleport to any position you want with -bc.tele, using the two number arguments to specify the coordinates.
The last piece of jargon used in description of a suite is data load, the degree to which a suite will lengthen the time it takes to save a map and load it to playtest it, measured in objects. Any well-made suite will not accrue any significant active load, or effect on in-game framerate - such will only occur if a logic needs to be constantly making many regular calculations even when it is not actively in use, which none of the suites featured here do.
On August 27 '18, a new command processor was released that prevented other players from interrupting someone in chat who was inputting arguments for a command - their chat wouldn't be entered as the argument. Copies of MMTK and co. released before this date will not support this. Each suite will have its support for this feature listed in its manual entry. Another update was released at that date that allowed only admins to use gun tools when mmtk.adminNeeded was enabled, where before even players without admin rights could use them. That's all the initiation you will need before diving in.
4 Mapmaker's Toolkit Manual
4.1 Tookit Management
The Toolkit Logics themselves come with their own built-in commands, that are functional within any map with the logics plugged. They are all prefixed simply with "-.". These commands can be executed even when a command from a suite is requesting an argument - if you've chatted "-bc.tele" but want to then use the "-.dev" command, that command will function as normal without Toolkit thinking you're trying to teleport to the "-.dev location".
4.1.4 Commands
Spoiler: Show More
4.2 Basic Commands
The Basic Commands suite, prefixed with "-bc.", is a very diffuse set of tools that generally allow you to skip around sections of your map for further ease of playtesting and manipulate the map in a very basic manner. It's good to have on hand, but serves no particular specialized purpose, and is a good suite to let you ease in to learning the use of Toolkit.
4.2.1 Information
Data Load: 13 Walls 1 Door 1 Region of significant size 3 Guns 58 Triggers 5 Timers
Active Load: 4016 units of region area
Plug Compatibility: No requirements
1.3 Command Processor?: Yes
4.2.2 Gun Tools
- Kill Tool: Kills things where you click. Never have to make yourself an OP gun again when you want to get through a map faster to test certain elements of it. It has two different modes that are described in the documentation for the -bc.tm command below. Slot 9 by default.
- Blink Tool: Teleports the user to the cursor. Slot 8 by default.
- Revive Tool: Defibrillates the character at the cursor. Uses an actor to do this, so it may only revive characters of the actor's team, Beta. Slot 6 by default.
4.2.3 Setup
No setup is required. The following configuration is available within the suite logics' Setup section:
- A bc.DefaultToolLocation region, where all gun tools are teleported to at when the map is played
- bc.killToolMode: The default mode the Kill Tool is set to.
- bc.boomPower: The power of the explosion created by -bc.bom.
4.2.4 Commands
Spoiler: Show More
4.3 Gun Manipulator
Prefixed with "-gn.", these features allow you to manipulate guns within the map in a variety of ways. They have limitations that make them most suited for the kinds of weaponry used in standard MP arena maps.
4.3.1 Information
Data Load: 3 Walls 45 Guns 101 Triggers 6 Timers
Active Load: 71 units of region area
Plug Compatibility: Again, GN will likely not be of help regarding very complex, trigger-reliant weapon systems, if you happen to be working with something akin to that.
1.3 Command Processor?: Yes
4.3.2 Gun Tools
- Gun Move Tool: Allows you to click and drag on guns in the map and move them around. It uses a character of team Beta to do this, so it will only be able to pick up guns of Any Team. It has four different modes that are described in the documentation for the -gn.tm command below. Slot 8 by default.
- Gun Cloning Tool: Spawns a gun of the desired model and stat profile at the cursor. Slot 9 by default.
4.3.3 Setup
A formation of walls within the Setup section, along with the tiny region inside of it, must be moved to some off-map location where it won't be rendered. Beware; If it does start rendering due to failure to move it or a very far camera zoom, and Force Ragdoll Disappearment is enabled, guns used by the Gun Cloning Tool could despawn and break stuff. The following configuration is available within the suite logics' Setup section:
- A gn.DefaultToolLocation region, where all suite gun tools are teleported to at when the map is played
- gn.gunToolMode: The default mode the Gun Move Tool is set to. muh var consistency
- gn.cloneModsModel: The default gun model the Gun Cloning Tool spawns.
4.3.4 Commands
Spoiler: Show More
4.3.5 Gun Model ID Numbers
If you don't want to refer to this manual all the time, keep a .txt with all these handy. The Hound Walker Cannon, Vehicle Grenade Launcher, and Vehicle Minigun unfortunately cannot be cloned, from what it looks like.
If you don't want to refer to this manual all the time, keep a .txt with all these handy. The Hound Walker Cannon, Vehicle Grenade Launcher, and Vehicle Minigun unfortunately cannot be cloned, from what it looks like.
Spoiler: Show More
4.4 Level Design Tweaker
Prefixed with "-lt.", Level Design Tweaker lets you place walls in-game and delete them thereafter if necessary, operating primarily on gun tools. You may work with a limited pool of various types of walls, each of different dimensions. Switching between types is done by changing the Tool Mode of the Place Tool with -lt.tm. to the numerical ID of the desired type. If you have reached a placable limit of a particular wall type, deleting one of the same type will free up some space. Your options:
Numerical ID: Dimensions, in units X-Y - Amount that can be placed
- Type 1: 30x30 - 15 placable
- Type 2: 20x20 - 20 placable
- Type 3: 30x110 - 10 placable
- Type 4: 110x30 - 10 placable
- Type 5: 100x100 - 5 placable
4.4.1 Information
Data Load: 67 Doors 102 Triggers 2 Guns 4 Timers
Active Load: 143 units of region area
Plug Compatibility: No requirements
1.3 Command Processor?: Yes
4.4.2 Gun Tools
- Wall Place Tool: Places a wall; its upper-left corner will be located at the cursor.
- Wall Delete Tool: Deletes the placed wall located at the cursor. You must aim at the upper-left of the desired wall.
4.4.3 Setup
No setup is required. The following configuration is available within the suite logics' Setup section:
- A lt.DefaultToolLocation region, where all suite gun tools are teleported to at when the map is played
4.4.4 Commands
Spoiler: Show More
4.5 Variable Manipulator
Variable Manipulator, prefixed with "-vm.", is the most robust of these 4 suites, but also requires the most involved setup. It allows you to view and change the value of any variable in the map, or utilize the neat variable "breaking" feature described below. Variables used within any part of the Toolkit logics or the suites themselves are all fair game, by the way, if you want to toggle adminNeeded on the fly. VM contains no gun tools.
4.5.1 Information
Data Load: 21 minimum triggers, + 1 for each variable; 4 timers
Active Load: 21 minimum units of region area, + 2 for each variable
Plug Compatibility: No requirements
1.3 Command Processor?: Yes
4.5.2 Setup
Each variable you want to be able to be modified by VM must be set up. The instructions for including a single new variable to manipulate into the suite are as follows:
Spoiler: Show More
- 1. Variable Logic Skeleton
- 2. Column Guide
- 3. Prefab Variable Logics
Whenever you want to add a new variable to VM, you must copy and paste the Variable Logic Skeleton, and the 2 tiny regions inside of it. In order to make it functional, you will need to edit 3 parameters of its trigger actions:
Spoiler: Show More
Parameters filled in with "O" must be erased and then filled in with the exact name of the desired variable.
The parameter filled in with "-vm.N" will define the name of the command you will use to manipulate the variable. N stands for nickname; replacing it with the exact name of your variable is not required (although you may not simply leave it as "-vm.N"). Personally, I abbreviate the variable to its initials, for example, "bc.peaceZoomService" -> "-vm.pzs".
Next, the logics must be organized properly within the borders. This is important: If you don't physically move the pasted logics into the correct place, you won't be able to manipulate the variable. Each filled skeleton must be placed into columns, each trigger within the column being offset 30y from the next, and each column, 40x from the next one. The third item in the diagram, 3, Prefab Variable Logics, are a set of pre-pasted logics arranged in this fashion, all filled in with O and N as we went over, that you may set up out of the box.
Spoiler: Show More
4.5.4 Commands
Spoiler: Show More
5 Conclusion & The Future
Everything about Toolkit was designed to be highly modular. New features can be added to the foundation provided by Toolkit logics with ease, and then used - by anyone. I intend for the community to be able to add on to the core concepts i've presented here in such a manner over time, building up a wider selection of mapmaking tools and make some stuff happen on a larger scale. I myself will, in the future, be bringing new suites to the table, each with their own forum thread and independent development, but with an inclusion process as painless as with the 4 original Suites here. Perhaps you will take a fancy to the idea yourself, hm? Without further adieu:
You may freely take, modify, and redistribute any part of the Mapmaker's Toolkit source and use it for any purpose, without need for any accreditation.
What will this forum thread be used for in the future? I've decided to have it solely serve the purpose of reporting updates on the core Toolkit logics and these 4 suites, plus discussion. Further additions I make to Toolkit will be made with their own threads, likely within the format "Mapmaker's Toolkit: Name of Suite".
On the off chance that someone needs more than 60 variables simultaneously available for manipulation with VM, the maximum the setup section can hold, let me know.
5.1 Credits
- Ditzy contributed a major mathematical system used by Level Design Tweaker's internal functioning.