Scripting Mapping Overview

So-called "scripting mapping" does not refer to using code to automate mapping, but rather to inserting and running Virtools scripts (hereafter referred to as scripts) inside a map.

As mapping techniques have continued to develop, we discovered ways to insert scripts into maps. This lets us manipulate objects in the map at runtime, enabling features that are completely impossible with traditional mapping — for example, tampering with the game's underlying mechanics or creating entirely new gameplay. The emergence of scripts has greatly enriched the playability of custom maps (from both the player's and the mapper's perspective), though the barrier to entry for scripts is higher than for regular mapping.

Before We Start

Although scripting mapping is not particularly complicated, it does require some foundation. Before you start learning scripting mapping, we recommend that you first master the following:

• Being able to create a traditional custom map on your own (obviously — the prerequisite for making a script map is knowing how to map)
• Understanding the basic operations of Virtools (knowing how to import/export nmo and move the camera is enough)
• Having some programming background (knowing what variables and functions are is enough)
• Having a basic vocabulary (the requirement is actually not high — even just being willing to look up words is fine, mainly because vt has no Chinese localization)
• Having some understanding of game development (this is a higher bar for beginners, but it's fine if you don't — just having interest is enough)

If you cannot meet the above requirements, we suggest starting with Traditional Mapping and gradually learning about mapping and Ballance's game mechanics, which will help you better understand and master scripting mapping.

Script Map References

Because Virtools is a very old tool, its early versions have long been lost on the internet. Most of the techniques we have now come from our continuous exploration and experimentation, standing on the shoulders of our predecessors and climbing ever higher. Often, it is hard to find complete references, and we can only rely on drawing inferences. Therefore, for newcomers, the ability to draw inferences and to reference other existing scripts is actually a crucial skill.

Below is a list of custom maps that have appeared since script maps emerged, with script-created gameplay at their core:

• Queen Ball
• Mi Wu (Misty Fog)
• Xiao Xiao De Lv Tu (A Tiny Journey)
• All We Know
• Jing Hua Shui Yue (Flower in the Mirror, Moon on the Water)
• ......

Disclaimer

The above list is in no particular order. If anything is missing, additions are welcome! You can also head over to the Map Download Site to find more script maps to play on your own.

References

In addition to referencing other people's mapping works, you can also consult 《Textbook of Creating Scripts in Maps of Ballance》, a scripting mapping tutorial compiled by 9826HZg and co-authored by Chris Xiong, GE ColdStar, hhmmdd123, BallanceBug, yyc12345 and other experts. This manual also drew upon and referenced this book when it was written.

Start Learning

You can first check out Quick Start and follow the tutorial's guidance to actually create a simple "custom map with scripts." Really, what learning scripting requires is a mindset of continuous trial and error, and not fearing difficulty. Theoretical knowledge can be filled in gradually, so we recommend reading the manual with a concrete need in mind.

Good luck!