hide results

    Mod Developer Guide by rezzzman

    Version: 1.0 | Updated: 10/03/08 | Printable Version | Search This Guide

                         Vampire the Masquerade Bloodlines(PC)
                                 Mod Development Guide
                                    May 25, 2008
                                     Version 1.0
                            Written by:  Dheu
                                 Email:  Dheuster@gmail.com
                           Use subject:  BloodlinesDevGuide 1.0
              Living Document: (read before emailing anyone)
              This is a living document.
              If you see any mistakes, or have anything that you want to add, email
              me and I will add you to the update list. (You will need a google
              If you make additions/corrections, be certain to give yourself
              credit in the Contributing Authors section at the end of the
    This Tutorial\FAQ was also published at:
    Official 1.2 Patch : vtmb_1_2.exe 15.2 MB (15,973,576 bytes)
    This Document looks best in a fixed-width font, such as Courier New.
    Vampire The Masquerade Bloodlines is Copyright © 2004 by Activision
    I am not affiliated with Activision or anyone who had anything to do with the
    creation of this game.  This Document may be posted on any site. You may not
    charge for, or in any way profit from this Document.
                                  Table of Contents:
      I.       Basics
        I.1       Game Architecture
        I.2       Enabling the Game Console
        I.3       Standard Tools
        I.4       VPK Files
      II.      Getting Started
        II.1      Creating a baseline
        II.2      Unofficial Patches
        II.3      Uncompressing Game Files\Change Management
      III.     Introduction to Python
        III.1     The __main__ Object
        III.2     Executing Python commands from Console.
        III.3     Executing Console commands from Python
        III.4     Entities
        III.5     Creating Entities with Python
        III.6     Events
        III.7     Input\Output
        III.8     Bringing it all Together
        III.9     Known Bugs
      IV.      Dialogs
       IV.1       Dialog Basics
       IV.2       DLG File Format
       IV.3       Special Conditions and Colored Responses
       IV.4       Dialog Engine Commands and Flow Control
       IV.5       Considerations and Scripting
       IV.6       Dialog Engine Bugs
      V.       Dialog Audio Synchronization
        V.1       DLG, VCD and LIP Files
        V.2       VCD Internals
        V.3       LIP Internals
        V.4       Creating Custom Audio
      VI.      Animating NPCs with Python
       VI.1       Skeletal Animations
       VI.2       Facial Expressions
       VI.3       Dispositions
       VI.4       Schedules and ScriptedDisciplines
       VI.5       Gestures and interesting_place
       VI.6       scripted_sequence and logic_choreographed_scene
      VII.     Editing Models/Skins
       VII.1      Basics
       VII.2      MDL File Details
       VII.3      Working with downloaded Skins
       VII.4      Editing Skins yourself
      VIII.    Cameras and Cut scenes
      IX.      Custom Items
      X.       Miscellaneous
      XI.      Legalities
      XII.     Common Scenarios and Examples
    Frequently Asked Questions
    VTMB Links
      A.       Entity Classes
      B.       Map Names
      C.       Item Name Summary
      D.       Game States
      E.      Common Models  : http://docs.google.com/Doc?id=dhgs89mq_3gtwn2chb
      F.      VCLAN Values   : http://docs.google.com/Doc?id=dhgs89mq_4fgq4nrfg
      F.5.6   VCLAN Values   : http://docs.google.com/Doc?id=dhgs89mq_5cxmzw4vg
      G       Entity Details : http://docs.google.com/Doc?id=dhgs89mq_6fmx3cxgt
      H       Animations     : http://docs.google.com/Doc?id=dhgs89mq_7dbfdbwdh
      I       Gestures       : http://docs.google.com/Doc?id=dhgs89mq_8fpssv86r
      J       Console Vars   : http://docs.google.com/Doc?id=dhgs89mq_10cfs83dqp
    Contributing Authors
    Final Words....
    I. > > > >  Basics
      These notes make certain assumptions about the person reading them. In short,
      I assume the reader is a programmer of some ilk, who either has python
      experience or has enough general programming experience that you can pick up
      Python from a good tutorial in about 30 min.
    I.1  > > > >  Game Architecture
      The game is composed of 5 Major parts:
      1) The game engine:
           You generally don’t touch this part. It handles rendering
           the 3D environment, managing input, output and events. VTMB
           uses an early prototype version of the Valve Source Engine for
           rendering and event management. (Basically fully functional
           except Enemy AI).
      2) Map files:
           Map files (.bsp) serve 2 purposes. They define the visual environment
           and also provide an initial set of objects within those environments.
           Eembedded objects include characters, trigger zones, sound emitters,
           invisible cameras and patrol path nodes. (If you have experience with
           Never Winter Nights editing, some of this may sound familiar.)
           For those that are new to this, I will simply say that there is a lot
           of invisible objects hidden on maps that you can’t see that help
           make things easier for the game engine.
      3) Models:
           Model files (.mdl) provide the look and feel of objects when rendered
           within the Map. These are read in at run time and injected into the map.
           (maps contain "pointers" to these models, but not the model data
           Some MDL files don’t contain any model data, but only contain
           animations. This is discussed more below.
      4) Sounds:
           Ever watch a movie with the sound turned off? Gets real boring real
           fast.  On the other hand, you can take a crappy looking 16 color sprite
           and give it a human voice and it adds a whole new dimension of
           interaction.  VTMB uses wav files for background music and ambient
           sounds. It uses mp3s for dialogs.
      5) Scripts
           A good scripting language is what separates RPGs from Action games.
           Scripts allow developers to compose cut scenes, conversations, remember
           choices and edit the environment based on user actions.  The scripting
           language for bloodlines is python, and it is the glue that holds the
           game together.
    I.2  > > > >  Enabling the Game Console
      Since VTMB doesn’t come with a slick Map Editor like Neverwinter Nights,
      modding the game will involve a lot of work within the game itself. For
      example, you may need to scout out locations, characters and animation
      sequences for re-use. To this end, you will need the console.
      To Enable the console, Right click the icon you use to start the game. Go to
      "Properties" and add –console to the target. The new launch target should
      look something like:
      "C:\Program Files\Activision\Vampire - Bloodlines\vampire.exe" -console
      STEAM USERS : Right Click VTMB link in Steam, select Properties and
                    the Set launch options. Add "-console" (without quotes)
                    to the input box. You may have problems if running VISTA.
      Now when you start the game, the console will appear. Hit the tilde (~) to
      Hide/unhide the console.
      The console comes with hundreds of commands to help developers and players
      alike. Simply hit a letter to see all commands that start with that letter.
      Type "HELP <COMMAND>" to see more info on a specific command. A full
      listing of commands and variables is included in attached Appendix J.
      I found the following commands invaluable during the development of my MOD.
          notarget [0/1]
              Enemies do not see you (invisibility)
          draw_hud 0:
              Removes the hud.
          noclip [0/1]
              Walk through walls. More importantly, disables the activation of
          cl_showfps 1:
              Shows your frame rate (important when testing models)
          cl_showpos 1:
              Shows your position and map name.
              Quite possibly the most useful console command the game has to offer.
              Displays a bounding box around any entities you approach which show
              additional entity information such as its base class and instance
              Shows list of game maps
          map <map name> (no bsp)
              Teleport to a map. Be warned that scripts often assume a certain game
              state, so if you teleport somewhere before you would normally have
              access to it, things may break. Even starting a conversation may
              cause the game to crash.
              logs a list of all entity classes currently in memory to the console.
              Unfortunately, it doesn't tell you the instance name. ( you will need
              to use some python for that)
              give the name of an entity class (typically found using the previous
              command), this function will list the entities "inputs" and
              "outputs". The inputs translate to functions that you can call on
              the entity. Some entities inherit functions from their parents. In
              these situations, not all functions are seen. But it’s a good
              starting point.
             The outputs translate to events that the entity can detect (and
             then re-throw). You can only detect events with embedded entities.
             See Appendix G for a full listing of entity functions and events
          ent_dump <instance_name>:
              Given the name of an entity, prints all properties and attributes
              associated with it to console. Sometimes you have to name the
              instance first.
              > FindPlayer().SetName("pc")
              > ent_dump pc
          createplayer :
              Even though you may think you are starting the game over, you are in
              fact only rebuilding your own character. Once creation process is
              over, the game resumes in your last location. You will lose all
              attributes an XP.
          vstat get "attribute" value
              console method of increasing stats. Negative values are ignored.
      Less useful, but still interesting:
              Displays "interesting places" as phone-booth sized cubes scattered
              about the map. These are like magnets and pull NPCs toward them. When
              the NPC enters, they perform an action associated with the booth. The
              booths have info overlaid; typically the default action that an NPC
              will perform when they enter the "booth".
          cl_entityreport 1
              Displays a list of all entity instances. Unfortunately, most of the
              info is C++ related: C classes and vector data that we can't touch
              from python.
          cl_pdump #
              Display additional entity info on screen. Pass in the entity number
              retrieved using either picker or cl_entityreport. set to -1 to
      For a full list of commands use : cmdlist
      For a list of both variables and commands use : cvarlist
      The console is connected directly to the game engine. If a command is entered
      that the engine does not recognize, it relays the command to the python
      shell. This means you can access python objects and methods from console. As
      you learn more about python, you will be able to do even more from the
      console. However trying to call python functions immediately from
      autoexec.cfg or user.cfg wont work as the shell isn’t initialized when those
      modules load. You can however define aliases and bind keys that
      will execute python functions at a later time.
          Using the console outside of the game menus can make the game unstable.
          Specifically, displaying the console normally pauses the game and when
          you click on the [X] in the top right corner to remove the console,
          sometimes the game will remain paused. This behavior is mostly
          If this happens to you; in order to get the game to un-pause you need to
          hide the console from a game menu. IE : hit ESC, enable/hide the console,
          then hit ESC to return the game. I have also been told that going to the
          character stats window will un-pause the game.
          If you wish to avoid the possibility of Locking/Freezing, simply make a
          habit of going to the game menu before activating console.
    I.3  > > > >  Standard Tools
      VPKTool :
          === THE === modding tool for VTMB. The most recent release is version
          3.9a and you can access it here:
          or from Turfster's website:
          ** It is also included with all of WESP's patches
          VPKTool is really all you need for basic modding. However there are other
          tools that help with specific aspects.
      Python 2.1.2
          The scripting language that the original game used. You can download the
          original shell here. It may also have been distributed with this Dev
          The main thing here is the IDLE editor, which provides indention and
          Color coding support.
          DialogEditor is handy for visualizing character dialogs. Unfortunately
          it doesn’t allow you to edit conditions or actions, making it almost
          useless for creating dialogs. But if your goal is to update existing
          lines,  Or review spelling in new text that you did by hand, then it is a
          Bear in mind when NPCs talk, they are playing pre-recorded audio. So
          While you can change player responses, you can’t change what the NPCs
          say.  There is room for limited ADDITIONS and new material).
          A set of Python scripts by ZylonBane that allow you to grab objects and
          move them around within a map. More importantly, it has the ability to
          save off all the map data. Basically the scripts allow runtime editing of
          the maps. Very cool if your mod will involve editing the maps.
      Now, if you want to actually EDIT models or Skins or introduce new custom
      content into the game, you may need some additional software. The original
      game was built using Maya for texturing and 3D Studio Max for models.
      The best free stuff that I know of is Blender3D for Model editing and Gimp
      for Image editing. There is a blender import plug-in for importing the models
      into Blender. It requires the installation of python.
      If you own Half Life 2, you can download the Steam Software Development Kit
      via Steam. The SDK offers tools for editing MDL models. While steams tools
      are easier to use than Blender, editing models is a complicated task for
      common users regardless of the tool.
      The general editing and re-skinning of models is outside the scope of this
      tutorial, however I will touch on some of the basics.
    I.4  > > > >  VPK Files
      If you look inside the Bloodlines installation directory, you will notice
      some large files with the extension .vpk. All the resources for the game are
      compressed within these files. This serves 3 purposes:
      1) Faster Loading:
         Easier to ask the OS to retrieve 1 big file than 300 small files.
      2) Smaller Footprint:
         Hey, who wants the game to take up another 5 gigs?
      3) User Overrides:
         When a user extracts a resource from the .vpk file and places it within
         the Vampires installation directory, (directory structure intact), the
         game engine will load the users uncompress version on startup instead of
         the one in the VPK file. While this design allows user mods, the downside
         is that it only allows 1 User Mod to be installed at a time.
    II  > > > >  Getting Started
      There are some pre-emptive steps that need to be taken care of before you can
      really begin modding. At a bare minimum, you must uncompress the files into a
      state in which you can make changes to them. This may be all you need if you
      are just playing around and feeling out what you can do. However, if you wish
      to share your mod with other people, you will eventually need to keep track
      of your changes, build a zip file for distribution and provide instructions
      for installing it.
      If you are a forward thinker, you can take some steps now to make the
      distribution and installation instructions easier to create and manage.
    II.1  > > > >  Creating a baseline
      A baseline is a snapshot of all the files in your game folder BEFORE you
      start editing them. If a user has a different version of the game than the
      one you build your mod upon, they may break their game if they install your
      mod. For this reason, Most mod developers will provide very specific
      instructions for installing their mod. These instructions generally go
      something like:
        1) Install a fresh copy of VTMB (you MUST uninstall if it exists)
        2) Install the Official 1.2 patch from <website> (Steam Users Ignore)
        3) Extract zip file to <installation dir>/Vampire
      The official 1.2 patch is supported by the Distributor, so despite being
      an external dependency (not included in your mod distribution), it is
      relatively safe to assume it will be around for many years.
      Unfortunately, Troika went out of business shortly after releasing VTMB so
      there is no expectation that new official patches will be release. Luckily,
      the Official 1.2 patch is still very much playable. A few misspelled words, a
      few side quests that may not open up if you don’t do things in the right
      order. However, the main quest is solid.
      That said, if you search around the Internet you will likely see Fan
      supported "Unofficial Patches". Read below for more info:
    II.2  > > > >  Unofficial Patches
      Unofficial patches are user built mods (much like what you may be endeavoring
      to create). Some simply fix scripting and timing issues with the original
      game. Some re-introduce content that wasn't linked into the original game.
      Some of the more advanced patches actually update the game engine and/or add
      support for higher resolutions and textures.
      Problems with Unofficial Patches:
      - Unofficial patches are NOT supported by a distributor. They are supported
        by an every day guy like yourself.  Unlike companies, human beings are
        fickle. Relying on someone else’s work creates a high-risk external
        dependency. Will the patch still be around when you are done? You must
        think forward. Not just weeks and months, but years into the future.
      - There is more than 1 mod out there with the term "Patch" in it. If you tell
        someone to download an unofficial "patch", you must also be certain to
        specify the AUTHOR and hope users get the right one. The safest bet is to
        use an actual url and hope the site is still up in 12 months.
      - Some Unofficial Patches come in the form of an installable executable. It
        is dangerous to ask users to install an executable, period. Taking the
        risk yourself is one thing, asking someone else to do the same is another.
      - The more installation requirements you place on users, the less likely
        someone is to take the time out to install your mod.
      Most of the issues above can be solved through MOD EXTENSION:
        Basically, you use the 1.2 patch as your baseline, but then install an
        unofficial patch/mod on top of your baseline, keeping track of all the
        files it installs/touches. When you package up your mod, you include the
        patch files as part of your distribution. By distributing the patch with
        your mod, you remove the risk of your baseline disappearing and decrease
        the work required by the user.
        If you DISTRIBUTE someone else’s work with yours, you should ask for
        permission. Furthermore, you should make it clear when you ask for
        permission that your mod will likely introduce modifications to their
      My recommendation:
        I advise checking out some of the Unofficial patches. You want to avoid
        requiring users to install ANYTHING other than the official patches and
        your mod. As such, you are looking for permission to include the desired
        patch in your mod's distribution. If you can’t find an author willing to
        grant permission. Then use the Official 1.2 patch.
        Before I get swamped with emails, I personally used Wesp’s 5.6 "Basic"
        patch as Wesp kindly granted permission to distribute the patch contents
        with my mod.
        Note that his permission was not granted for you and your mod. If you wish
        to use an unofficial patch, you must contact the author.
        You CAN and SHOULD install this game twice on the same computer. To do so,
        simply install the game (and any patches), rename the directory and then
        use the games uninstaller. Now install again. You will be able to run
        both copies independently. (If you are a steam user, you may need to make
        a dos based batch script to rename the base directory so that the version
        you wish to run gets executed.)
    II.3  > > > >  Uncompressing Game Files\Change Management
      In the introduction to this section, we discussed the concept of change
      management: keeping track of what you change now so that you can create a
      distribution later.
      You can approach change management in one of two ways
      - Install the game and manually keep track of the files that you edit
          Typical strategy for single man teams making "small" mods that don’t
          touch many files. Unfortunately, most people don’t know how many files
          they will be touching when they begin development.
      - Set up software to track the changes for you.
          With 76,000 support files, this is recommended for anyone planning on
          making SUBSTANTIAL changes to the game. It is also a must if you plan
          on sharing development tasks with other people.
          Unfortunately, setting up software change management can take up to 3
          hours even with my step by step instructions. If you are unsure,
          I recommend installing 2 copies of the game and START by using
          manual change management.
      A) Manual change management
        1) Install a FRESH COPY of VTMB
           - Yes, you should uninstall first if it is already installed.
           - DO NOT run the game after install
        2) Install the Official 1.2 Patch
           - Go to http://www.vampirebloodlines.com/patch/
           - Download latest Patch (1.2)
           - Install, use defaults
           - DO NOT run the game after install
           You don’t need to keep track of changes made by the 1.2 patch,
           but just for your general information and amusement, the 1.2
           patch updates the following files:
           It also adds the following vpk files:
                 - Empty
                 - dlg\Hollywood\isaac.dlg
                 - dlg\main characters\regent.dlg
                 - dlg\santa monica\e.dlg
                 - vdata\hackerterminals\haven_pc.txt
                 - vdata\hackerterminals\shrekhub2_terminal.txt
                 - vdata\system\infobartypes.txt
                 - vdata\system\strings.txt
        3) Uncompress VPK files
           - Run VPKTool
           - Goto VPK Extractor Tab
           - Check "0 length wav fix", open "<install_dir>\Vampire\pack000.vpk"
           - Right Click -> Select All
           - Right Click -> Extract
           - Repeat extraction for all VPK files IN ORDER from smallest to largest.
             ORDER IS IMPORTANT! Some files will report errors, don’t worry.
        4) Remove Compiled Python files (.pyc)
           Python source code is stored in ".pk" files. When a pk file is loaded by
           the game engine, it automatically compiles it into a .pyc file. The game
           engine knows to do this based on the time stamp of the files. If the PK
           file is newer than the PYC file, then the PYC is out of date and needs
           to be recompiled.
           The original VPK files don’t contain any .py scripts, but they DO
           contain .pyc files. The 1.2 Patch installs .pk files, but not
           pyc. As a result, you have a mix match: 1.2 pk files and 1.0
           pyc files. The issue is that the pyc files are 1.0, but have a
           newer timestamp, therefore the game engine will not compile the
           If I have lost you, don’t worry about it. To resolve this mix up, we
           simply delete all .pyc files under the Vampire/python subdirectory
        5) [optional] Install Unofficial Patch (that you have permission to use)
           - Note, whether it came as a zip or an exe,  keep a copy of the original
             patch around for later reference.
        6) [optional] Extract Metadata From Map(bsp) : 3-4 hours
             To add entities and other items to maps, you will need to edit the map
             data.  This is done by opening a map using VPK Tool, extracting
             its data (in text form),  changing it and then writing it back.
             If you extract the text data from all the maps into text versions of
             the maps upfront, you can search the data for examples of how to set
             up entities/ camera shots, event handlers etc...
             There are a lot of maps and it takes VPKTool a while to extract the
             data. So even streamlined, this can take 3 to 4 hours.
             To streamline the process, I have included a directory called meta
             with this guide that contains all the map names with the extension
             .txt. Copy the meta directory to your Vampire/maps directory.
             Whether you use my included files or make them yourself, once you
             have a directory of mirrored empty text files, use VPK Tool to
             open up the binary versions (in the parent directory) one at a time,
             copying the contents to the text version under meta.
             If you don’t have the patience, you don’t have to do this step right
             now. You can extract/save off to the meta directory AS NEEDED.
      B) Setting up Software Change Management
        1) Install tortoiseSVN
           - Go to http://tortoisesvn.tigris.org/
           - Download correct version
           - Install, use defaults
           - Restart Computer
        2) Create Repository
           - Open Windows Explorer
           - Create a new folder and name it. For example: C:\svnrepo (Drive should
             have at least 10 Gigs of free space)
           - Right-click on the newly created folder and select:
             TortoiseSVN -> Create repository here...
           - Choose a repo type. I used native. Berkeley wont work over a Network
             drive if you plan on splitting up development tasks with other team
             members later.
           A repository is then created inside the new folder. DO NOT EDIT THOSE
           FILES YOUSELF!
        3) Install a FRESH COPY of VTMB
           - Yes, you should uninstall first if it is already installed.
           - DO NOT run the game after install
        4) Install 1.2 Official Patch
           - Go to http://www.vampirebloodlines.com/patch/
           - Download latest Patch (1.2)
           - Install, use defaults
           - DO NOT run the game after install
        5) Uncompress VPK files
           - Run VPKTool
           - Goto VPK Extractor Tab
           - Check "0 length wav fix", open "<install_dir>\Vampire\pack000.vpk"
           - Right Click -> Select All
           - Right Click -> Extract
           - Repeat extraction for all VPK files IN ORDER from smallest to largest.
             ORDER IS IMPORTANT! Some files will report errors, don’t worry.
        6) Remove Compiled Python scripts
           - Traverse <install_dir>/Vampire/python directories and DELETE any .pyc
             files. (pyc = compiled python files) See Manual Version Control step 4
             above if you would like to see explanation
        7) Import the VTMB directory into the Repository:
           - Using Explorer, browser to C:\Program Files\Activision (or equivalent)
           - Right Click "Vampire – Bloodlines" and select: TortoiseSVN -> Import
           - Use the browse button [...] to select the REPO : (file:///C:/svnrepo)
           - Take a nap or something. Import takes about 1.5 hours.
        8) Check Out the Code Base:
           - Right Click "Vampire – Bloodlines" and DELETE it.
           - Right Click the C:\Program Files\Activision
           - Select "SVN checkout..."
           - Update Checkout Directory :
               C:\Program Files\Activision\Vampire - Bloodlines
           - It will begin the checkout process. Find something else to do for 1.5
        9) [optional] Install Unofficial Patch (that you have permission to use)
           - Note, whether it came as a zip or an exe,  keep a copy of the original
             patch around for later reference.
           - If you install an unofficial patch, you need to commit the changes
             after it is installed. Commit is like telling the computer to take a
             "snapshot" of the directory. You can restore to any snapshot at a
             later time (or compare what has changed)
           - Revisit the installation directory (C:\Program Files\Activision)
           - You should see an explanation point icon over "Vampire - Bloodlines"
             (This means changes have been detected).
           - Right Click "Vampire – Bloodlines", Select:
               Tortoise SVN -> Check For Modifications. (Depending on the patch it
               may take  while.)
           - Click on the "Text Status" Table Header to re-order by that.
           - Anything marked "non-versioned" is new and has been ADDED by the
           - Use SHIFT_CLICK to highlight all non-versioned items. Right click your
             hi-lighted list and select "Add" (Then close dialog with [OK]
           - Right Click "Vampire - Bloodlines" and select "SVN Commit..."
           - As message, put name or version of unofficial patch. Hit [OK]
        10) [optional] Extract Metadata From Map Files : 3-4 hours
             To add entities and other items to maps, you will need to edit the map
             data.  This is done by opening a map using VPK Tool, extracting
             its data (in text form), changing it and then writing it back.
             If you extract the text data from all the maps into text versions of
             the maps upfront, you can baseline your map data and use "Diff"
             functionality to compare changes made to maps. Furthermore, you can
             search the text based data for examples of how to set up entities/
             camera shots, event handlers etc...
             There are a lot of maps and it takes VPKTool a while to extract the
             data. Even streamlined, this can take 3 to 4 hours.
             To streamline the process, I have included a directory called meta
             with this guide that contains all the map names with the extension
             .txt. Copy the meta directory to your Vampire/maps directory.
             Whether you use my included files or make them yourself, once you
             have a directory of mirrored empty text files, use VPK Tool to
             open up the binary versions (in the parent directory) one at a time,
             copying the contents to the text version under meta.
             If you don’t have the patience, you don’t have to do this step right
             now. You can extract/save off to the meta directory AS NEEDED.
      C) Developer Notes : How did I create the meta directory:
        I installed cygwin and then:
        $ cd "/cygdrive/c/Program Files/[...]/Vampire/maps/meta"
        $ touch `ls .. –l | awk '{print $9}'`
        $ for f in *.bsp ; do mv $f `echo $f | sed 's/\(.*\.\)bsp/\1txt/'` ; done
    III  > > > >  Introduction to Python
      VTMB uses a stripped down version of Python 2.1.2. Like JavaScript, Python
      is a high level programming language that is relatively easy to pick up.
      Python is used to "glue" the game together. Its role is similar to that of
      an orchestra conductor. That is, it mostly conducts already existing
      objects into doing things at the right time. For example, orchestrating a
      cut scene.
      I recommend downloading python 2.1.2 if you will be editing the scripts in
      this game. The Python distribution will install IDLE, a nice Python editor
      and will also include documentation for that version of the language so
      that you know what other commands are available to you.
      However, you do not HAVE to download python. The game comes with a minimal
      python shell built in. From the console, you can type "import <filename>.py"
      and the game will automatically compile any non-compiled python scripts.
      If there are any errors, it displays the errors to the console. If you
      edited one of the python scripts that came with the game (and errors were
      detected), the game reverts to the original script distributed in the .vpk
      Basic python functionality is included, but advanced python modules such as
      threading and OS are not. You must be careful not to use the more advanced
      Python modules from your game scrtips (such as "re") or the game will crash.
        - Python has a special object called None which represents, you guessed
          it: NOTHING. If used within a conditional, None acts the same way as a
          Boolean value of false.
        - Python only receives input from the C++ engine. You cannot capture input
          directly from the user (without hacky workarounds).
        - Console commands go strait to the C++ Engine.  Only unrecognized commands
          get sent along to the Python Shell. Be careful when defining console
          ]a=2                    <- python assignment to new variable a
          ]alias a "echo Hello"   <- console alias a executes "echo Hello"
          ]a=3                    <- intercepted by console, results in error.
      For a quick tutorial on Python (lists, maps, tuples, for loops,
      method definitions, etc...) I recommend:
    III.1  > > > >  The __main__ Object
        The VTMB python shell is loaded when you start VTMB. At start up, the
        system initializes a standard python root level object called "__main__"
        Here is a list of the VTMB methods made available via the __main__ object.
          Entity    __main__.FindEntityByName(str name)
            Searches for a single entity on the map with the name specified. If
            a single entity is found, returns the Entity. If more than one Entity
            by the same name is found, throws an exception. If no entity is found
            by that name, returns None.
          Entity[]  __main__.FindEntitiesByName(str name)
            Searches for any entity by the name specified on the current map. If
            found, returns an array of Entities. If none are found, returns None.
            Note : The string may contain the wild card "*":
            Example: FindEntitiesByName("cop_*")
          Entity[]  __main__.FindEntitiesByClass(str class)
            Searches for any entity belonging to the CLASS specified on the current
            map. If found, returns an array of Entities. If none are found, returns
          Character __main__.FindPlayer()
            Returns an object handle to the Player. If the player does not exist
            (because a game has not been loaded), returns None.
          void      __main__.ChangeMap(string MapName)
            Changes Map. See Appendix B for map name listing. You can also type
            "maps" in the console for a list of maps.
          Entity    __main__.CreateEntityNoSpawn(str class,tpl loc,tpl facing )
            First step of creating a new Entity Using Python. This allows you
            to set the entity up (model, name, location, etc) before actually
            spawning it with the CallEntitySpawn() method.
          void      __main__.CallEntitySpawn(Entity ptr)
            Spawns an unspawned entity defined with CreateEntityNoSpawn.
          void      __main__.ScheduleTask(float delay, String Command)
            Threading support. Executes command in parallel to current thread. You
            can use a delay of 0.0 if you simply want to fork, or you can use
            another delay if you want to give the engine time to do something.
          void      __main__.SquadSeesPlayer
            The idea is that you enter an area with hostiles who don’t attack
            (because they cant see you).  In practice, enemies normally don’t go
            hostile till a conversation ends or you enter a trigger area. This
            command is relatively unused.
          bool      __main__.OneOfSet
            This command is used by dialogs to prevent choices from showing up
            several times. For example, maybe you have a line that can show up if
            the person has Persuasion 5 OR Seduction 5. But what if the PC has
            both? You don’t want the option showing up twice. See the dialog
            section below (VIII) for more info and an example of use.
        Here is a list of the variables\properties made available via the
        __main__ object:
          __main__.ccmd   <- Access to console commands
          __main__.cvar   <- Access to console variables
          __main__.G      <- Global storage (Remembered by Save game).
          NOTE : __main__.G does not exist until the user starts a new
                 game or loads a save game.
    III.2  > > > >  Executing Python commands from Console.
        So how do we access this "__main__" object? As mentioned in section I.2,
        the console is connected directly to the game engine. However, if a command
        is entered that the engine does not recognize, it is passed along to the
        python shell.
        This means you can access python objects and methods from console:
        Furthermore, if the method is a child of __main__, you do not have to
        explicitly specify __main__. Though it is a good habit to get into and
        helps to ensure you don’t conflict with console objects.
        You can also define simple 1 line python methods.
          ]def hello(s): print "Hello [%s]" % (s)
        Then you can run your function:
          Hello [World]
        If you use the Python introspection command "dir" to examine __main__’s
        You will now see hello() as one of __main__’s methods. You will also likely
        notice a lot more methods than the small list in III.1. This is because
        most maps in VTMB load a city specific python script with helper functions.
        Python uses the line return to separate commands and indentation to
        indicate function blocks (scope). In other words, to create anything beyond
        a simple 1 line method, you must define your function in an external file
        and import it.
            |Ex: Filename = [<install root>\Vampire\python\custom.py]            |
            |import __main__                                                     |
            |                                                                    |
            |def showInstances(prefix="npc_V"):                                   |
            |    entities = __main__.FindEntitiesByClass(prefix+"*")             |
            |    print "Class                                  Name"             |
            |    print "--------------------------------------------------------"|
            |    for ent in entities:                                            |
            |        name=""                                                     |
            |        try: name=ent.GetName()                                     |
            |        except: pass                                                |
            |        if name != "":                                              |
            |            print "%s %s" % (ent.classname.ljust(35),ent.GetName()) |
        Once created, you can import the file using the import command:
        ]import custom
        Class                                  Name"
    III.3  > > > >  Executing Console commands from Python
        So now that you know how to use console to execute Python, how do you
        execute one of those handy console commands from python?
        Console commands are accessed through the ccmd variable:
        Console variables are accessed through the cvar variable:
        e.g. :
            |Ex: Filename = [<install root>\Vampire\python\custom.py]            |
            |import __main__                                                     |
            |                                                                    |
            |def debugMode():                                                    |
            |  __main__.cvar.draw_hud=0                                          |
            |  __main__.cvar.cl_showfps=1                                        |
            |  __main__.cvar.cl_showpos=1                                        |
            |  try: __main__.ccmd.notarget()                                     |
            |  except: pass                                                      |
            |  try: __main__.ccmd.noclip()                                       |
            |  except: pass                                                      |
            |  try: __main__.ccmd.picker()                                       |
            |  except: pass                                                      |
        Bugs and Limitations:
          The cvar pointer is very useful, however the ccmd pointer is less
          useful. I have played around with the command and it does not
          appear as though the C++ handler recognizes parameters. Furthermore,
          while you can call methods that do not take parameters, any method
          called always throws an unspecified exception (however, it still
          works). Therefore you must either place the call within a try
          catch as I did above, or you can avoid the error message by assigning
          the function name to a string. This also results in the function being
          called but avoids sending the error message to console.
        Hack/Work Around:
          Luckily, the ccmd command can be used to invoke custom aliases. If you
          define a custom alias within Vampire/cfg/autoexec.cfg that executes the
          contents of a .cfg file:
          alias execonsole "exec console.cfg"
          You can use python file io to write commands to the console.cfg file and
          then execute them using your alias.
            |Ex: Filename = [<install root>\Vampire\python\custom.py]            |
            |import __main__                                                     |
            |                                                                    |
            | def console(data=""):                                              |
            |   if data=="": return                                              |
            |   cfg=open('Vampire/cfg/console.cfg', 'w')                         |
            |   try: cfg.write(data)                                             |
            |   finally: cfg.close()                                             |
            |   __main__.ccmd.execonsole=""                                      |
            ] oldname=__main__.cvar.name
            ] __main__.cvar.name="Yukie"
            ] import custom
            ] custom.console("vclan 124")
            NOTES: vclan can crash the game if the appropriate model is not
                   In precache. Use with caution.
    III.4  > > > >  Entities
      From Python's perspective, all game objects are Entities: characters,
      triggers, cameras, even some script sequences are grouped together as
      entities. They come in 2 flavors: Embedded and Dynamic. Python can be used to
      manipulate either.
      A) Embedded Entities
          As the name implies, Embedded entities are embedded into the map data.
          These entities must exist before the game is started. You can remove, add
          or edit embedded entities using the map editing tools provided by
          After uncompressing VPK files, you will find the Map data under the
          The Maps themselves are also compressed as .bsp files. Using VPKTool,
          we can futher uncompress the map data into META Data.
          NOTES: Generally speaking, I will open the map in question, highlight
                 all the metadata and paste it into notepad. As mentioned in the
                 Getting Started chapter, I recommend saving a new file, named
                 after the map (but with .txt extension), possibly within the sub
                 directly "/Vampire/maps/meta".
          The metadata is basically a laundry list of object declarations. It
          is pretty easy to read, but it is MASSIVE and can be overwhelming at
          What is so special about Embedded Entities? Embedded entities provide
          FULL ACCESS to all the properties and events that an entity supports.
          The game engine does some things when a map loads that can only be
          done at that time. For example, hooking up events. For this reason,
          you MUST USE embedded entities if you need to receive events or set some
          non-accessible properties/attributes. If you need user Interaction
          (Dialog), you MUST use Embedded Entities.
      B) Dynamic Entities
          Dynamic entities are not known to the engine when the map loads.
          Since some things can only be done when the map loads (setting up
          events), there are limitations on what can be done with dynamic
          When you create a dynamic entity, it will receive default values for all
          of its' properties. Some of these can be changed. For example, you can
          change the model of a dynamically created NPC because there is a method
          called "SetModel" which provides access to that property/attribute.
          However, you can NOT change the dialog that an NPC speaks because there
          is no method for changing an NPC's associated dialog file.
          For those properties that can not be changed, you are stuck with the
          default values. The inability to change/set all properties is irritating
          and in some cases make things impossible.
          For example, since you can't set the dialog of a dynamic NPC, you can't
          dynamically create NPC's that the PC can talk to. If you want dialog
          interaction, you have to use embedded entities.
          Other notable limitations/irritations:
            - Dynamically spawned npc_V* classes have no clipping area (you walk
              through them like ghosts). I believe this is because the default
              "solid" property is 0 or SOLID_NONE. Luckily other entity types such
              as props ARE solid by default.
            - You can’t define event handlers for Dynamic entities such as
            - Some entities have properties that must have valid values in order to
              successfully spawn. If the default value is invalid and you can't
              set it, then you effectively can't create that entity dynamically.
              Example : npc_maker
      C) Entity Scope
          Embedded or Dynamic, entities are inherently local to the map they are
          defined/created on. The GetName\SetName method mentioned in III.4 implies
          all Entities have a name. All entities CAN have a name, but they do not
          necessarily have a name, nor are their names necessarily unique.
          A game/map designer can guarantee that within a particular map, a
          specific entity name exists and is unique, but that is about it. Luckily,
          that is generally all you need to ensure your camera sequences and cut
          scenes work correctly.
          That said, if you are modding the game, you must be careful not to create
          a new Entity with the same name as an existing entity within the map,
          else you may cause Unexpected behavior.
    III.5   > > > >  Creating Entities with Python
      Spawning items from Python is a 3 step process: Create, Set Properties, Spawn
      A) Create :
         The "Creation" step is done with the method:
         __main__.CreateEntityNoSpawn(String classname, Location, Facing)
         The function takes 3 parameters:
           classname :  This is the main parameter. It is a string value which
                        determines what additional attributes, properties and
                        methods the entity INSTANCE will have. See Appendix A
                        for a list of known classname Strings. For this example,
                        we will use npc_VVampire.
           Location : A 3 float tuple. representing x,y and z coordinates. Most
                      People use the Player’s current location for the value.
                        ex: myloc = (1.0,2.0,3.0)
                        myloc = __main__.FindPlayer().GetOrigin()
           Facing : Yet another 3 float tuple. The first float Represents angle,
                    up or down, that the character is looking. (are you looking up
                    at the ceiling or down at the floor). The second is what
                    direction they are facing right to left. The 3rd is
                    forwards/backwards motion.
                        ex : myFacing = (0.0, 180.00, 0.00)
                        myFacing = __main__.FindPlayer().GetAngles()
         Code Example:
           pc = __main__.FindPlayer()
           loc = pc.GetOrigin()
           ent = __main__.CreateEntityNoSpawn("npc_VVampire", loc, (0,0,0) )
      B) Set Properties
         Some Entities have REQUIRED properties or the call to spawn will fail.
         NPCs require that you set a model value for example.
         In making this, I didn’t have the time to go through and test each
         entity type for required parameters, so you will just have to figure
         it out as you go. When you try to spawn an entity, you will receive
         errors messages telling you what must be set to proceed.
         In attached Appendix G, I provide a list of properties and methods for
         each specific classname. However, those methods do not include methods
         inherited from parents. For example, npc_VVampire extends a C++
         base Class (referred to as the Proxy Class) which extends the
         Python Character class which extends the Entity Class: Each of
         these "layers" adds more methods to the final instance.
         Methods provided by the npc_VVampire classname:
            AllowAlertLookaround        AllowKickHintUse    BarterBegin
            ChangeMasqueradeLevel       AllowOpenDoors      BarterEnd
            ClearActiveDisciplines      ChangeSchedule      Bloodgain
            FadeHeadAsCameraTarget      ClearPatrolPath     BloodHeal
            FadeBodyAsCameraTarget      FollowPatrolPath    Bloodloss
            LookAtEntityCenter          FrenzyTrigger       DisableThink
            LookAtEntityDefault         FrenzyUpdate        Faint
            LookAtEntityOrigin          Inventory_Remove    FadeToSkin
            pl_criminal_attack          LookAtEntityEye     FleeAndDie
            pl_supernatural_attack      MakeInvincible      FrenzyCheck
            pl_supernatural_flee        pl_criminal_flee    HumanityAdd
            SetBloodShieldDiscipline    pl_investigate      HungerCheck
            SetBodyAsCameraTarget       physdamagescale     MoneyAdd
            SetDefaultDialogCamera      PlayDialogFile      MoneyRemove
            SetDontFacePlayerInDialog   SetBodygroup        MoveToDest
            SetHeadAsCameraTarget       SetBossMonster      MoveToHome
            SetInvestigateMode          SetFallToGround     PlayFloat
            SetInvestigateModeCombat    SetFollowerBoss     RotateToDest
            SetMovementMultiplier       SetFollowerType     RotateToHome
            SetScriptedDiscipline       SetRelationship     skin
            SpawnTempParticle           SetSkinFadeTime     TakeDamage
            StartPlayerDialog           SetSpeechVolume     TweakParam
            StartPlayerDialogRemote     SetupPatrolType     WalkToNode
            StartPlayerDialogUnforced   StayEntrenched      WillTalk
            TeleportToEntity            UseInteresting
         Methods provided b the Proxy base class:
             Alpha                           ClearParent
             Kill                            Color
             ScriptHide                      SetFakeSilence
             SetParent                       ScriptUnhide
             SetSoundOverrideEnt             Use
         Methods provided by the Character base class: NOTE: From this point
         down, ALL npcs have these methods:
             GiveAmmo                         AmmoCount
             GiveItem                         BumpStat
             HasItem                          DialogDiscipline
             IsFollowerOf                     GetQuestState
             RemoveItem                       HasWeaponEquipped
             SeductiveFeed                    IsMale
             SetCamera                        React
             SetDisposition                   SetQuest
             SetExpression                    StartBarter
             SetGesture                       WorldMap
         Methods Provided by the Entity base class: NOTE: From this point
         down, ALL entities have these methods:
             GetAngles                        GetCenter
             GetAngleVectors                  GetModelName
             GetName                          GetOrigin
             IsAlive                          SetModel
             SetAngles                        SetOrigin
         Methods Provided by the Python PyObject base object (part of the
         language spec). NOTE: All python objects support these methods:
             __getattr__()                    __setattr__()
             __dict__()                       __doc__()
             All entity INSTANCES have attributes, however attributes are read-
             only. If you spawn an entity and set its name. e.g. :
            You can use the console to see its attributes :
                 ent_dump "test"
             This will dump all attributes to the console. You can then read
             the attributes using dot notation.
             Some entities have a method called TweakParam() which will allow you
             to edit select attributes. If you scan the source code, you will see
             it only used to change vision, hearing and squad.
      C) Spawn:
          Once all desired/required properties are set, we spawn the object with
          the command:
          It is important to note that despite all the methods above, not all
          npc_VVampire class attributes are being exposed. For example, there is a
          "dialogname" attribute which allows dialogs, but no method for setting it
          from python. Therefore, we can not dynamically create an NPC that can
          have a dialog with the PC using the standard dialog engine.
          In the case of npc_maker, the class requires you to set an NPCType
          attribute to spawn, however there is no setter from python. Therefore the
          entity can’t be created dynamically at all.
          See Section XII : Common Scenarios,  for a more robust spawn example
    III.6  > > > >  Events
      The game engine supports hundreds of events. However, only embedded entities
      receive events. I will tell you upfront that there is no way to receive or
      handle game events from python ALONE. If you wish to receive/handle events
      you will HAVE to work with events already established or embed new entities
      into the maps.
      A) ENTITIES:
          The vast majority of entities only handle events meant for the entity
          itself. For example, if you embed an npc_Vhuman (see Attached Appendix
          G), you can set it up so that it receives an OnDialogBegin event and
          calls a python method:
          "classname" "npc_VHuman"
          "targetname" "customNPC"
          "OnDialogBegin" ",,,0,-1,OnBeginDialog('customNPC'),"
          That is rather strait forward, but what about the awkward string with
          commas? Here is a break down of the event protocol;
          "<entity name>,<method>,<param>,<delay>,<max fires>,<python script>,"
          <entity name> : Can be any named entity within the same map. The name
                          should NOT be in quotes.
          <method>      : Name of a valid method on the target entity to fire. Each
                          entity supports different methods. See attached Appendix
                          G for a full listing.
          <param>       : Optional parameter to pass into the method. If the method
                          requires more than 1 parameter, you have to use the
                          <python script> option.
          <delay>       : Delay in seconds before calling the method. Can be
                          floating point value.
          <max fires>   : As the name implies, maximum number of times the event
                          will fire.  A value of –1 means there is no maximum and
                          it will always fire.
          <python script> Call a global or module specific python method.
          Example: To create an opponent that begins a conversation with you when
                   They Lose half of their health the first time, but not a second
          "classname" "npc_VVampire"
          "targetname" "customNPC"
          "OnHalfHealth" " customNPC, StartPlayerDialogRemote,,0,1,,"
          To activate multiple methods, you simply embed the event handler multiple
          Times. Here we disable any vampire disciplines when we start the convo.
          "classname" "npc_VVampire"
          "targetname" "customNPC"
          "OnHalfHealth" " customNPC, StartPlayerDialogRemote,,0,1,,"
          "OnHalfHealth" " customNPC, ClearActiveDisciplines,,0,-1,,"
      B) Player Events:
          It is cool that you can receive events about entities you create, but
          what about the player? You don’t exactly create the player? There is a
          special entity called events_player that you can plug into a map to
          receive player events. (From Appendix G):
          output: OnFrenzyBegin
          output: OnFrenzyEnd
          output: OnWolfMorphBegin           (Animalism War Form)
          output: OnWolfMorphEnd             (Animalism War Form)
          output: OnPlayerTookDamage
          output: OnPlayerKilled
          output: OnPlayerSoundLoud
          output: OnActivateAuspex
          output: OnActivateCelerity
          output: OnActivateCorpusVampirus   (Blood Buff)
          output: OnActivateFortitude
          output: OnActivateObfuscate
          output: OnActivatePotence
          output: OnActivatePresense
          output: OnActivateProtean
          output: OnActivateAnimalismLvl1
          output: OnActivateAnimalismLvl2
          output: OnActivateDementationLvl1
          output: OnActivateDementationLvl2
          output: OnActivateDominateLvl1
          output: OnActivateDominateLvl2
          output: OnActivateThaumaturgyLvl1
          output: OnActivateThaumaturgyLvl2
          input: EnableOutputs
          input: DisableOutputs
          input: CreateControllerNPC
          input: RemoveControllerNPC
          input: AwardExp
          input: ClearDialogCombatTimers
          input: ImmobilizePlayer
          input: MobilizePlayer
          input: RemoveDisciplines
          input: RemoveDisciplinesNow
          input: MakePlayerUnkillable
          input: MakePlayerKillable
      C) World Events
          Like events_player, the events_world object lets you key into certain
          global events: (From Appendix G):
          output: OnCopsOutside
          output: OnCopsComing
          output: OnStartCopPursuitMode
          output: OnEndCopPursuitMode
          output: OnStartCopAlertMode
          output: OnEndCopAlertMode
          output: OnStartHunterPursuitMode
          output: OnEndHunterPursuitMode
          output: OnMasqueradeLevel1
          output: OnMasqueradeLevel2
          output: OnMasqueradeLevel3
          output: OnMasqueradeLevel4
          output: OnMasqueradeLevel5
          output: OnMasqueradeLevelChanged
          output: OnPlayerHasNoBlood
          output: OnCombatMusicStart
          output: OnCombatMusicEnd
          output: OnAlertMusicStart
          output: OnAlertMusicEnd
          output: OnNormalMusicStart
          output: OnNormalMusicEnd
          output: OnUseBegin
          output: OnUseEnd
          input: SetSafeArea
          input: SetCopWaitArea
          input: SetCopGrace
          input: SetNosferatuTolerant
          input: SetNoFrenzyArea
          input: AIEnable
          input: FadeGlobalWetness
          input: HideCutsceneInterferingEntities
          input: UnhideCutsceneInterferingEntities
          input: PlayEndCredits
          input: ClearDialogCombatTimers
          Of all the events, the two I personally found the most useful were
          OnCombatMusicStart and OnNormalMusicStart. These (not so well named
          events) basically signify the start and end of combat. If you maintain
          an "InCombat" flag, you can also use OnBeginNormalMusic to indicate
          when a map has been loaded from a save game.
      D) Other/Misc Events
          You may have noticed there are a few events missing, like entering a
          map, the player going stealth or the player picking up an item. I wont
          pretend to possess a comprehensive knowledge of all events, but I can
          tell you about what I have discovered and some workarounds I have
          For entering maps, you can embed a logic_auto entity:
          "classname" "logic_auto"
          " spawnflags" "0"
          "OnMapLoad" ",,,0,-1,OnEnterMap('sm_hub_1'),"
          "origin" "-2420.54 -2558.76 -111.97"
          ** ALL Maps (.bsp) already have a logic_auto entity embedded into them
             which loads a python script associated with the city that the map is
             located in. Hence the subdirectories under Vampire/Python.
          Note that OnEnterMap will only fire when actually traversing into a map
          from another map. Loading a save game will not cause the event to fire.
          However, when you load a save game, OnBeginNormalMusic will still fire.
          For detecting item pickup, you can use a trigger_inventory_check:
          "classname" "trigger_inventory_check"
          "targetname" "inventory_check"
          "StartDisabled" "0"
          "spawnflags" "1"
          "itemname" "item_w_tire_iron"
          "OnPlayerHasItem" "inventory_check,Disable,,0,-1,,"
          "OnPlayerHasItem" " popup_35,OpenWindow,,0.5,-1, ,"
          Some events are not supported. For example, detecting that the player
          has gone stealth (crouches).  You can design workarounds for some. For
          stealth, you can poll certain states using a logic_timer entity:
         "classname" "logic_timer"
         "StartDisabled" "0"
         "UseRandomTime" "0"
         "RefireTime" "15.0"
         "OnTimer" ",,,0,-1,OnPollEvent(),"
         "origin" "-2420.54 -2558.76 -111.97"
         (In vamputil.py)
         def OnPollEvent():
             global stealth
             pc = __main__.FindPlayer()
             crouched = ((pc.GetCenter()[2] - pc.GetOrigin()[2]) == 18)
             if not stealth:
                 if (pc.active_obfuscate or crouched):
                 if (not pc.active_obfuscate and not crouched):
      E) Events to Avoid:
          There isn’t an easy to detect leaving a map as most maps have multiple
          exit points. The PC may be teleported away to a different map by a door,
          an area trigger, a conversation. There about half a dozen ways to exit an
          area and you would have to search and update every entity on the map and
          every dialog associated with every entity on the map. Even then you may
          miss something embedded in a python event script. In general, I would
          avoid designing a mod that relies on the ability to detect when the
          player leaves an area.
          Globally detecting events that are normally defined on a per-entity basis
          is generally a no no.  For example, detecting when things die. That would
          involve lots of map edits. The more stuff you edit, the greater the
          chance for bugs.
      D) Companion Mod
          I don’t mean to plug my mod, but as I built my companion mod it
          occurred to me that others may want to make mods as well (hence this
          guide). I added the events described above to pretty much every map.
          But instead of having them call my specific functions, I had them
          call global methods that I defined in vamputil.py. That way other
          mod developers could hook into those events easily.
          If you are doing something small that only impacts 1 map, you will
          probably want to keep your mod small and only make the edits to that map
          But if your goals are larger and you need events like I describe above
          throughout the entire game, you may consider downloading my mod
          and starting from there as a lot of the groundwork has already been
    III.7  > > > >  Input\Output
      In general, direct user input/output from python is a no-no. I describe some
      workarounds below, but most of these are theoretical and have not been
      A) INPUT:
         Within VTMB, input is generally done using dialogs. You enter a
         conversation with someone, make some choices and the dialog system
         fires some of your python methods as a result.
         VTMB does not support receiving user input DIRECTLY into python. There
         is a hacky work around, but I don’t recommend it. Still I will describe it
         below for completeness:
         Building upon the console hack I described in section III.3, you can save
         off the users current configuration, rebind keys to python methods to pass
         key press events into python
         data  ="host_writeconfig backup.cfg\n"
         data+=’bind "1" "OnInput(\’1\’)"\n’
         data+=’bind "2" "OnInput(\’2\’)"\n’
         data+=’bind "3" "OnInput(\’3\’)"\n’
         data+=’bind "4" "OnInput(\’4\’)"\n’
         data+=’bind "ENTER" "OnInputFinish()"\n’
         data+=’bind "ESC" "OnInputCancel()"\n’
         and then later, when you are done, restore the keyboard config:
         data="exec backup.cfg"
         The primary danger with this is if the user exits the game before
         finishing your home-made user input prompt, they may lose their
         configuration. There are ways to mitigate the danger (look for backup.cfg
         within vamputils and restore/delete if found).
         Even with a mitigation strategy, ultimately this is a kludge. Hopefully
         you can design your mod so that you do not need user input beyond what can
         be gained using a normal dialog file.
      B) OUTPUT:
         I am aware of 4 ways of getting data to the user.
         1) hud_timer objects can be used to show time or any number to the
            user that can fit within a clock like sequence (00:00:00). For
            example, I used this in my companion mod to show hits remaining
            when you possess a traveling companion or how much time is
            left before you can re-feed. FYI : There is a HUD Counter, but
            I could never get it to work.
         2) game_sign objects rely on files which describe a background
            and text. Typically, the files are pre-fabricated within your
            vdata directory and game_sign entities that reference the files are
            embedded into maps. You call the OpenWindow() method on them to make
            them appear.
            One downside of a game sign is that the game pauses while the sign is
         3) If you look up the game_sign entity in Appendix G, you will notice that
            it has a ChangeFile() method on it. Using Python file io, you can
            dynamically construct a sign file, save it off, create a game_sign
            entity on the fly (doesn’t have to be embedded), Change the file to the
            temp file you created and then call open window. This elaborate work
            around would allow you to open professional looking text presentation
            windows to the user from python without edits to the map files.
            Combined with the (mitigated) input hack above, you could simulate a
            decent looking user prompt.
            Bear in mind that game signs pause the game. So If you were to use this
            hack to create your own dialog system, you wouldn't be able to animate
            NPCs for emotion, nor would their mouths move if you told them to
            speak a dialog line. There may be other uses for the hack, but I
            haven’t thought of any yet.
         4) For simple feedback, you can use the console hack in conjunction with
            the "say" command to have text print to the upper left corner of the
            hud. The text will appear to have been said by the current value of
    III.8  > > > >  Bringing it all together
      So we can call both python AND console commands. We can access both python
      and console variables. This means you can tackle most tasks using one
      approach or the other. If you get stuck or run into a bug, you have a
      backup plan.
      For example, take the vclan console command. If you issue that command and
      the clan tries to load a model that isn’t currently in memory, you get
      a pre-cache error and the game crashes. This holds true for other commands
      like npc_create and the console version of SetModel. However, if you change
      the pc model using Python, the model is loaded into memory and the crash does
      not occur.
      In the case of creating new objects, you can use python to be more precise
      about What you want. You can assign a name, location, facing, initial model,
      hearing,  vision, squad and health. (health is done by changing the cvar
      sk_basenpctroika_health variable before and after spawn)
          A) Useful Console Commands (to call from python)
                  self explanatory
                  brief earthquake (think explosion)
                  self explanatory
                  self explanatory
              vclan <clan number>  :
                  change clan of protagonist. Also resets stats to 1/0
              npc_freeze :
                 "Freezes" npc under crosshair.  You can then search all npcs
                 (examine npc.playbackrate) to discover which one the PC is looking
                  at Nice work around for "grappling" NPCs from python.
              teleport_player "entity_name"
                  Needed when you wish to teleport the PC somewhere and set their
                  facing. Bear in mind that pc.SetOrigin() also works for
                  teleportation within a map, but pc.SetAngles() does not. (all the
                  time) This console command correctly changes the facing.
          B) Useful Player Objects and Commands
              Enables the following commands:
              ]pc.WorldMap(int WorldMap_State)
                  Opens up the world map city chooser for teleporting to
                  various cities.  WorldMap states vary thoughout the game. The
                  "up to date" value is generally maintained by
                  __main__.G.WorldMap_State , however you can enter whatever
                  value you want.
              ]pc.BumpStat(string "attribute_name" , int value)
                  Can be used to RAISE pc stats. Negative values are ignored.
                  NOTE: In order to lower a stat, you must "reset" the player
                        using the console command vclan and then restore stats.
                        You can get the players current clan number using
              ]pc.GiveItem(string "item_name")
                  Give yourself an item, provided you have the patients to look up
                  its item code. The console version "give" is actually nicer as it
                  auto-lists all the built in item codes.
              ]pc.giveAmmo(string  "item_w_...",int amount)
                  Name pretty much says it all. It should be noted that giveAmmo
                  works on stackable items such as bloodpacks.
              ]pc.SetModel(string "model_path")
                  Unlike the console version, this one wont crash the game if the
                  model is not already in memory.
                  Works for both positive and negative numbers.
                  Gives PC blood. When the game starts, the PC has a maximum blood
                  pool of 15
                  Take blood away from PC.
                  Gives PC money
                  Activates the bloodheal discipline even if you don’t have it.
                  Heals a small amount of health for some of your blood pool
                  Accepts both positive and negative values. Negative is good.
                  Positive is bad.
              ]pc.CalcFeat(string type)
                  Feat values are the result of skills, attributes and items. This
                  function does the calculation for you.
                      if pc.CalcFeat("haggle") == 3
        Additional pc controls can be installed on a per map basis by injecting
        an events_player object into a map (if one is not found). See III.5.B
        If you name the PC:
        you can retrieve a list of PC attributes using the ent_dump command:
        ]ent_dump "pc"
    III.9  > > > >  Known Bugs
      Make no mistake, VTMB is a C++ based game. The engine is not written in
      Python and the objects exposed to python are merely proxies to the actual
      objects in C++. Your control over the objects is limited to what the game
      engine exposes to you (via the input methods). This confused me at first as I
      thought I could set/change every attribute I saw using the ent_dump command
      from Python. This simply isn’t true. (Though you can use vstats to change
      many of the player attributes).
        So I built a mod and then during testing, the game kept crashing when
        the player would change maps. 2 days later, I traced the bug down. Here
        was the problem:
        __main__.G.somestring=FindPlayer().GetName()        <-- OK
        __main__.G.someint=FindPlayer().clan                <-- OK
        __main__.G.somefloat=FindPlayer().GetOrigin()[2]    <-- OK
        __main__.G.someinstance=FindPlayer()                <-- NOT OK
       The issue here is that FindPlayer() returns a runtime instance. The same
       can be said for FindEntityByName, FindEntitiesByName and
       __main__.G gets saved with your save game. While you can store properties of
       entities as part of a save game, you can not save off any instance pointers
       or you will crash the game.
       This rule holds true for G and sub attributes of a G (hash maps, lists, etc)
       or Entities attributes as they are saved off as part of the save game.
       Module scope global variables and local scope variables are NOT
       saved as part of the save Game and are therefore safe: You temporarily
       store instances references.
       The "G" Delimma:
       Vamputil.py gets loaded with the game and its methods are available from
       every map, so it makes sense to add your module imports there. However,
       there is a snag. Vamputil gets imported by the game before the game has set
       up the persistent "G" variable.
       This causes 2 issues.
       ISSUE 1:
       Take this scenario:
            import foo
          from __main__ import *
          def somefunction():
              G.persist = "1"
      The issue is that when the game imported foo, G didn’t exist. So when foo
      imported * from __main__, it didn’t get G. when the function gets called,
      an exception will be thrown. Two possible workarounds. One is to import G
      locally from methods that access it.
          def somefunction():
              from __main__ import G
              G.persist = "1"
      The other work around is to ONLY import __main__ and not import anything from
      It. Reference elements of __main__  explicitly from the code. This causes a
      runtime lookup and avoids the exception.
          import __main__
          def somefunction():
              __main__.G.persist = "1"
      ISSUE 2:
      If a variable does not exist on G, that is fine. You can test for the
      variables using a simple if statement:
      If not __main__.G.somevariable:
      However, complex data structures will throw exceptions. For example
      If not __main__.G.somehasmap["valiue"]: exception thrown
      Many times a module needs to initialize and setup lists and
      hashmaps managed by the module when the player first starts the
      game. Of course we have the issue above: G doesn’t exist when
      vamputils loads. So initialization needs to happen from a secondary
      method that happens after vamputils loads.
      There are 2 solutions.
      First solution is to embed a logic_auto entity in one of the early maps
      (sm_pawnshop_1.bsp -> Your apartment at the beginning of the game)
      and have it call your initialization method there.
      "classname" "logic_auto"
      "spawnflags" "0"
      "OnMapLoad" ",,,0,1,yourmodule.initialize(),"
      "origin" "-2420.54 -2558.76 -111.97"
      The second solution is similar to the first. But instead of installing your
      own logic_auto entity, you simply add your code to
      python/santimonica/santimonica.py which basically gets loaded by a logic_auto
      entity that is already installed in the map.
      Minor Invincibility bugs:
      There are 4 ways of making the pc invincible. You can use the console command
      "buddha". This allows the PC to get down to 1 hit point, but not actually
      die. There is an events_player method "MakePlayerUnkillable()". This allows
      The PC to get down to 1/4 their total hit points, but they will not go lower.
      There is the console command "god" which prevents the player from taking any
      damage period. And then there is the console variable debug_no_damage, which
      when set to true prevents anyone from taking damage (even enemies).
      Of these four methods, the first two only work if the PC is one of the 7
      standard clans. If you use vclan to change to a non-standard clan, then
      buddha and MakePlayerUnkillable will not stop the PC from dying.
    IV > > > > Dialogs
    IV.1 Dialog Basics
      So we have talked about Python and writing scripts, but how do we activate
      those scripts? The most common way within this game is a dialog.
      A) Where are they?
          Dialog files end with the extension ".dlg". Once you unpack the VPK
          files, you will find the Dialog files for the various game characters
          located under Vampire/dlg/...
      B) How are dialogs made accessible in game?
          Dialogs must be connected to an embedded game entity. The only way to
          add a new dialog to the game is to embed a new entity that links to your
          new dialog.
          Alternatively, you can edit an existing dialog that is already connected
          to an existing game entity. If you are new to this and you aren't
          comfortable messing with map files just yet, the second approach is a
          good way to get started.
      C) Can I change dialogs while the game is running?
          YES! You can!. While python scripts are compiled once per game (and then
          cached), dialogs are loaded into a special dialog engine each time you
          start a dialog. So if you make edits to a dialog, the next time you start
          the dialog, the edits will immediately be seen.
    IV.2 DLG File Format
      If you open up a dialog file, you will see a 13 column table defined with
      "{" and "}":
          { }{ }{ }{ }{ }{ }{ }{ }{ }{ }{ }{ }{ }
      The FIRST column is the row index. The first row should always
      have an index value of 1:
          {1}{ }{ }{ }{ }{ }{ }{ }{ }{ }{ }{ }{ }
          {2}{ }{ }{ }{ }{ }{ }{ }{ }{ }{ }{ }{ }
          {11}{ }{ }{ }{ }{ }{ }{ }{ }{ }{ }{ }{ }
          Not all row numbers have to be accounted for (There can be skips
          to allow people to add responses), however, all rows should appear in
          descending order.
      The SECOND column is what the NPC/PC says if the Protagonist is Male
          {1}{ Male : NPC Statement}{ }{ }{ }{ }{ }{ }{ }{ }{ }{ }{ }
          {2}{ Male : PC Response 1}{ }{ }{ }{ }{ }{ }{ }{ }{ }{ }{ }
          {3}{ Male : PC Response 2}{ }{ }{ }{ }{ }{ }{ }{ }{ }{ }{ }
      The THIRD column is what the NPC/PC says if the Protagonist is Female
           #  MALE   FEMALE
          {1}{Male}{ Female : NPC Statement}{ }{ }{ }{ }{ }{ }{ }{ }{ }{ }
          {2}{Male}{ Female : PC Response 1}{ }{ }{ }{ }{ }{ }{ }{ }{ }{ }
          {3}{Male}{ Female : PC Response 2}{ }{ }{ }{ }{ }{ }{ }{ }{ }{ }
      The FOURTH column contains an integer value which redirects to another
      row within the dialog file if the PC chooses that response. The special
      character # means it is an NPC statement
           #  MALE      FEMALE      NEXT
          {1}{NPC Male}{NPC Female}{ # }{ }{ }{ }{ }{ }{ }{ }{ }{ }
          {2}{PC Male }{PC Female }{ 5 }{ }{ }{ }{ }{ }{ }{ }{ }{ }
          {3}{PC Male }{PC Female }{ 7 }{ }{ }{ }{ }{ }{ }{ }{ }{ }
          {4}{        }{          }{   }{ }{ }{ }{ }{ }{ }{ }{ }{ }
          {5}{NPC Male}{NPC Female}{ # }{ }{ }{ }{ }{ }{ }{ }{ }{ }
          {6}{        }{          }{   }{ }{ }{ }{ }{ }{ }{ }{ }{ }
          {7}{NPC Male}{NPC Female}{ # }{ }{ }{ }{ }{ }{ }{ }{ }{ }
          When scanning for responses, the engine stops when it hits a row with a
          "#". The blank row is not necessary, but has been added to improve
      The FIFTH column is used for conditions. You can use python or one of the
      built in special conditions (See IV.2 below for Special Conditionals)
          The engine supports "and" logic operations using "and"
              {1}{M}{F}{5}{pc.armor==3 and npc.classname=="npc_VVampire"}
          The dialog engine supports "or" logic operations using "or", but the
          entire condition must be contained in parenthesis:
              {1}{M}{F}{5}{(pc.armor==3 or npc.classname=="npc_VVampire")}
          You wont see many "or" statements throughout the dialogs because you can
          achieve the same effect by using 2 lines.
          But what if both conditions are true? You don't want the same dialog line
          appearing twice. To solve this issue, the game engine provides a special
          command called "OneOfSet)". It is made specifically for the dialog engine
          and ensures only 1 dialog out of several will appear (the first one to
          evaluate true).
              {1}{M}{F}{5}{(pc.armor==3 and OneOfSet(1,2)}
              {2}{M}{F}{5}{(npc.classname=="npc_VVampire" and OneOfSet(2,2)}
      The SIXTH column allows you to execute 1 line of python script. If it is an
      NPC statement, the script will execute when the NPC says the statement. If it
      is within a choice, the script will only execute if the player chooses the
          Example Script: (In vamputils.py)
              def pcFollow(npc):
              def pcNFollow(npc):
          Example Dialog:
              {1}{NPC}{NPC}{#}{                     }{              }{}{}{}{}{}{}{}
              {2}{sit}{sit}{1}{npc.IsFollowerOf(pc) }{pcNFollow(npc)}{}{}{}{}{}{}{}
              {3}{go }{go }{1}{!npc.IsFollowerOf(pc)}{pcFollow(npc) }{}{}{}{}{}{}{}
              {4}{end}{end}{}{                      }{              }{}{}{}{}{}{}{}
              {5}{   }{   }{ }{                     }{              }{}{}{}{}{}{}{}
      The REMAINING COLUMNS (7-13) provide specific responses based on the PC's
          Column 7 = Brujah
          Column 8 = Gangrel
          Column 9 = Nosferatu
          Column 10 = Toreador
          Column 11 = Tremere
          Column 12 = Ventrue
          Column 13 = Malkavian
          Note that using these columns does not allow gender specific responses
          Which is one of the reasons they are not utilized more throughout the
          game. (If you want to use these, you can still SIMULATE gender specific
          responses by using starting conditionals. See IV.4).
    IV.3  Special Conditions and Colored Responses
      The special conditionals include:
          F_Seduction #
          M_Seduction #
          Seduction #
          Intimidate #
          Dominate #
          Persuasion #
          Dementation #
          Thaumaturgy #
          Humanity #
      Special conditions mean that the ability is equal to or greater than
      the number. Most result in responses with special colors/fonts. If
      the number is negative, then it means less than (the positive value
      of) the number and the font/color is not applied.
      You can perform "and" Boolean logic with the special conditionals,
      but you must use the special "&" operator:
          {1}{M}{F}{5}{Seduction 3 & pc.armor==3 and npc.class=="npc_VVampire"}
      You can NOT use "or" logic conditionals with the special conditions,
      however you can use separate lines and the "OneOfSet" command to
      simulate or conditionals:
          {1}{M}{F}{5}{(Seduction 5 & OneOfSet(1,2)}
          {2}{M}{F}{5}{(Persuation 5 & OneOfSet(2,2)}
      NOTES :
          The Dominate condition normally only appears if the player is Ventrue. If
          you wish to have dominate options appear for Tremere as well, there are
          two approaches:
           1) The best approach is to simply include a Thaumaturgy based
              response that also depends on a minimum dominate ability. You wont
              hear the domination sound and the blood points wont be subtracted,
              but the response will still be red.
              {5}{M}{F}{9}{ Dominate 4                                    }{...
              {6}{M}{F}{9}{ Thaumaturgy 1 & getattr(pc,"base_dominate")>3 }{...
           2) An alternate approach uses a dialog engine bug you can exploit:
              {5}{M}{F}{9}{ Dominate 4
              {5}{M}{F}{9}{ getattr(pc,"base_dominate")>3 and IsClan(pc,"Tremere"}
              The main 2 things to note here is that BOTH LINES HAVE THE SAME LINE
              NUMBER BUT ONLY 1 LINE EVALUATES TO TRUE. When the game engine
              parses the file, it scans the conditions and the text Content in two
              separate scans. When 2 lines have the same number it confuses the
              engine and treats both lines the same.
              From my experience, it seems the number of lines from the top of the
              file (not the line number or which condition is actually true)
              dictate which line controls how the text displays for both responses.
              Sometimes it is the top and sometimes it is the bottom. You have to
              test and possibly swap to get this trick to work.
              Unlike the previous approach, not only will the response be red, it
              will execute the dominate animation and produce the dominate sound
              when selected. It will even subtract the correct number of blood
              points. The really interesting thing about this bug is that it
              doesn't matter if the PC even has the dominate ability. All that
              matters is that only 1 condition evaluates to true and both lines
              have the same number (this can be used with any of the special
              abilities to color lines).
              I hesitated to even mention this exploit because the problem with it
              is that overuse quickly makes a mod un-maintainable. Dialogs
              containing this exploit are super-sensitive to editing. If someone
              adds new lines above your condition, the engine may suddenly begin
              using the wrong line to display. Having to re-test ALL the conditions
              every time the dialog is edited is cumbersome to say the least. So I
              recommend the first method, unless you are squeezed for space and
              only have room for 1 additional line number.
    IV.4  Dialog Engine Commands and Flow Control
      A) AUTO-END
         The auto-end command will automatically end the dialog if the command
         is reached. It is embedded in the response section surrounded by
             Below, there nothing but a single AUTO-END in the "Everyone" column,
             so the dialog will always end after the NPC's statement.
                 {201}{(STATEMENT MALE)}{STATEMENT FEMALE }{#}{ }{}{}{}{}{}{}{}{}
             In the second example below, the conversation will end unless the PC
             is a female.
                 {201}{(STATEMENT MALE)}{STATEMENT FEMALE }{#}{ }{}{}{}{}{}{}{}{}
                 {202}{(AUTO-END)}{I Don't Know}{0}{}{}{}{}{}{}{}{}{}
      B) AUTO-LINK
         The auto-link command will automatically link to a new line in the dialog
         when it is reached.
             Below, there nothing but a single AUTO-LINK in the "Everyone" column,
             so the dialog will link to the next NPC statement.
                 {201}{(STATEMENT MALE)}{STATEMENT FEMALE }{#}{ }{}{}{}{}{}{}{}{}
             Here is an advanced example. If the npc is following the pc and
             female, you will see a "no" response. If the npc is following the pc
             and male, the dialog forwards to 211. If the npc is NOT following
             the pc and the pc is male, you autolink to 221, otherwise you end.
                 {201}{(STATEMENT MALE)}{STATEMENT FEMALE }{#}{ }{}{}{}{}{}{}{}{}
                 {202}{(AUTO-END)}{}{0}{ }{}{}{}{}{}{}{}{}
      C) "..."
         "..." is a reserved NPC statement that basically represents no response.
         It mostly comes into play when an NPC statement does not have an
         associated audio file (discussed later).
         Normally when an NPC statement does not have an associated audio file,
         the text displays on the screen. Essentially the engine turns on
         sub-titles for the remainder of the dialog. To be certain that the
         player had a chance to read the text, the engine will prompt the
         user even if the dialog would normally end.
         For example, the following would show the NPC saying ".." and prompt
         the user to hit 1) to continue (if line 201 did not have any associated
                 {201}{.. }{.. }{#}{ }{}{}{}{}{}{}{}{}
                 {202}{(AUTO-END)}{}{0}{ }{}{}{}{}{}{}{}{}
         However, 3 periods and the dialog would end without prompting the user,
         even if there was no audio.
                 {201}{... }{... }{#}{ }{}{}{}{}{}{}{}{}
                 {202}{(AUTO-END)}{}{0}{ }{}{}{}{}{}{}{}{}
          At the bottom of most dialog files, you will find many lines marked as
          (STARTING CONDITION). When a dialog is loaded, the dialog engine searches
          for a block of STARTING CONDITIONALS at the end of the dialog. They are
          evaluated from top to bottom. As soon as the first condition evaluates to
          true, the engine is redirected to the NPCs first line. Note that you can
          not chain STARTING CONDITIONS (they can not redirect to another starting
          condition block.
              {2000}{(STARTING CONDITION)}{}{10}{ not pc.IsMale()}{}{}{}{}{}{}{}{}
              {2001}{(STARTING CONDITION)}{}{20}{ pc.Charisma>2()}{}{}{}{}{}{}{}{}
          Above, if the pc is female, you go to dialog at 10. If the PC is male and
          has decent charisma, you go to dialog at 20. If none of the starting
          conditions is true, the dialog attempts to start at the beginning of the
          file (line 1). Using a system like this, you could design clan specific
          responses for both genders.
          Code placed in the 6th column does NOT get executed with starting
          conditionals. HOWEVER, the conditional supports python and there is
          nothing to stop you from executing code in the conditional block
          This is mostly useful for fixing npcs before dialogs start:
             {200}{(STARTING CONDITION)}{}{0 }{ mySetup(npc)   }{}{}{}{}{}{}{}{}
             {201}{(STARTING CONDITION)}{}{10}{ not pc.IsMale()}{}{}{}{}{}{}{}{}
             {202}{(STARTING CONDITION)}{}{20}{ pc.Charisma>2()}{}{}{}{}{}{}{}{}
          (In Vamputils.py)
          def mySetup(npc):
              # do whatever
              return 0
          Notice that the line number of the first STARTING CONDITION is 0. When
          this is the case, the Starting Condition is evaluated but its result is
          ignored and it moves on. In other words, it doesn’t matter if
          mySetup(npc) returns 0 or 1, however we return 0 to be on the safe side.
      E) NOTES
          You can simulate secondary starting conditional blocks by creating a
          silent audio response (The line MUST have an associated sound file
          that plays nothing) followed by a group of (Auto-Link) lines with
              {10}{[silence] ...}{[silence] ... }{#}{}{}{}{}{}{}{}{}{}
              {2000}{(STARTING CONDITION)}{}{10}{ not pc.IsMale()}{}{}{}{}{}{}{}{}
              {2001}{(STARTING CONDITION)}{}{50}{ pc.IsMale()()}{}{}{}{}{}{}{}{}
          You can force what amounts to closed captioning for a specific
          dialog by first redirecting to a line with no associated audio file.
          When a line has no audio, close captioning is automatically turned on.
          It remains on until the dialog is over, even if the next response has
              {10}{...        }{...        }{#}{}{}{}{}{}{}{}{}{}
            {2000}{(STARTING CONDITION)}{}{10}{ not pc.IsMale()}{}{}{}{}{}{}{}{}
            {2001}{(STARTING CONDITION)}{}{50}{ pc.IsMale()()}{}{}{}{}{}{}{}{}
    IV.5  Considerations and Scripting
      A) Four choices per NPC Statement
          The dialog engine will display at most 4 responses. So you must be
          careful with conditionals to make sure you don’t introduce a bug. For
          example, a high level character could meet your Intimidation, Persuasion,
          Seduction and Domination criteria, making other responses unavailable.
          People also cheat.  Don’t assume just because it is the first
          conversation of the game that they will have "at most" some specific
          General rule of thumb : When possible, try to handle both branches of a
          conditional response (see below) so that you can accurately
          control/predict the number of responses and link to "<More...>" as
          a 4th response if more than 4 options may be possible.
              {1}{NPC Male}{NPC Female}{# }{                }{}{}{}{}{}{}{}{}
              {2}{PC Male }{PC Female }{5 }{ Persuasion 4   }{}{}{}{}{}{}{}{}
              {3}{PC Male }{PC Female }{5 }{ Persuasion -4  }{}{}{}{}{}{}{}{}
              {4}{        }{          }{  }{                }{}{}{}{}{}{}{}{}
              {5}{NPC Male}{NPC Female}{# }{                }{}{}{}{}{}{}{}{}
          You can also control the number of responses using the OneOfSet()
          command discussed earlier.
          The common scenario : You have a default way of getting through a
          dialog, but you want to offer a shortcut or special reward to someone
          who has invested into a character with Dialog Skills.
          You could display and handle lines for all possibilities (like above),
          or you could allow the user to take advantage of their most powerful
          dialog skill and not bother displaying the other options.
              {1}{Male }{Female}{#}{                            }{}{}{}{}{}{}{}{}
              {2}{max1 }{max 1}{10}{                            }{}{}{}{}{}{}{}{}
              {3}{max 2}{max 2}{20}{Dominate 3   & OneOfSet(1,4)}{}{}{}{}{}{}{}{}
              {4}{max 2}{max 2}{30}{Persuasion 5 & OneOfSet(2,4)}{}{}{}{}{}{}{}{}
              {5}{max 2}{max 2}{40}{Seduction 4  & OneOfSet(3,4)}{}{}{}{}{}{}{}{}
              {6}{max 2}{max 2}{50}{Intimidate 3 & OneOfSet(4,4)}{}{}{}{}{}{}{}{}
              {7}{max 3}{max 3}{60}{ }{}{}{}{}{}{}{}{}
          This allows you to keep track of when you might need to use a "<More>".
          Again, these are just ideas of how to help manage potential dialog
          bugs. In practice, you will normally end up using some combination
          of the examples above.
      B) Scripts and Fail fast execution
          When the conditional contains an AND, it uses FAILFAST execution. This
          means if the first condition fails, the second condition is not even
          executed. This is important if your function also performs additional
          hidden tasks. We will talk more about this later.
          When dealing with lots of conditionals it is also good practice to make
          the first response a de facto non-conditional response that ensures the
          game can continue.
      C) Advanced tricks
          For profession grade responses, you can build python functions to help
          guarantee all responses are seen. Basically you make some methods
          that execute with every displayed line to keep track of how many
          lines have displayed. Then, at the right moment, display more and
          link to the remaining choices.
          Example Script:
              |Filename = [<vampire root>/python/vamputil.py]                     |
              |import dialogutil                                                  |
              |Filename = [<vampire root>/python/dialogutil.py]                   |
              | from __main__ import Character                                    |
              | def _Reset(self):                                                 |
              |     self.dialogcounter=0                                          |
              | def _Count(self):                                                 |
              |     if self.dialogcounter == 3: return 1                          |
              |     self.dialogcounter += 1                                       |
              |     return 1                                                      |
              | def _IsMax(self):                                                 |
              |     if self.dialogcounter==3:                                     |
              |         self.Reset()                                              |
              |        return 1                                                   |
              |     return 0                                                      |
              | Character.Reset  = _Reset                                         |
              | Character.Count  = _Count                                         |
              | Character.IsMax  = _IsMax                                         |
          Example Dialog:
              {1}{Opening Line}{Opening Line}{ #  }{npc.Reset()}{}...
              {2}{Response1   }{Response1   }{    }{npc.Count()}{}...
              {3}{<More...>   }{<More...>   }{ 3  }{npc.IsMax()}{}...
              {4}{Response2   }{Response2   }{    }{npc.Count()}{}...
              {5}{<More...>   }{<More...>   }{ 5  }{npc.IsMax()}{}...
              {6}{Response3   }{Response3   }{    }{npc.Count()}{}...
              {7}{<More...>   }{<More...>   }{ 7  }{npc.IsMax()}{}...
              {8}{Response4   }{Response4   }{    }{npc.Count()}{}...
              {9}{<More...>   }{<More...>   }{ 9  }{npc.IsMax()}{}...
              {10}{Response5  }{Response5   }{    }{npc.Count()}{}...
              {11}{<More...>  }{<More...>   }{ 11 }{npc.IsMax()}{}...
              {12}Nevermind   }{Nevermind   }{    }{           }{}...
          Thanks to fail fast, as long as you put the npc.Count() method last
          within the conditional (5th) column, it will ensure the line isn't
          counted if an earlier condition fails. IE:
          {#}{Response  }{Response   }{    }{npc.IsMale() and npc.Count()}{}...
          If the line doesn't display because the npc is female, then it isn't
          Also notice that there is a <More...> every other line that redirects to
          itself.  And a Reset at the beginning.
          This allows you to build large, dynamic and complex dialogs without
          even having to think about weather a dialog option will appear or
    IV.6 Dialog Engine Bugs
      1) Do not assign to 2 dimensional arrays or 2 dimensional hash maps from
         dialog Files. Bug in the dialog engine seems to reset the array to null.
          module.My2DArray[1][2]="3"  <- will cause engine to set variable
                                           My2DArray to null.
          Wrap alterations to complex data structures with python methods. (This
          is a better practice anyway)
      2) Calling an npc_maker’s Spawn method will not work while the PC is in a
         dialog. There is no error, it simply will not spawn anything.
          - Use ScheduleTask() to delay spawn()
          - Call spawn from NPCs OnDialogEnd Event (If it is an NPC that you
      3) Single letter responses are ignored by the dialog engine.
          Example: None of these lines will display nor will any of their
                   conditions even execute for evaluation.
                  {1}{Some Question}{Some Question}{#}{}{}{}{}{}{}{}{}{}
                  {2}{A  }{1  }{10}{IsFollower("E")    }{}{}{}{}{}{}{}{}
                  {3}{B  }{2  }{20}{IsFollower("Lily") }{}{}{}{}{}{}{}{}
                  {4}{C  }{3  }{30}{IsFollower("VV")   }{}{}{}{}{}{}{}{}
                  {5}{D  }{4  }{40}{IsFollower("Knox") }{}{}{}{}{}{}{}{}
                  You need at least 2 non-space, non-tab letters for the engine
                  to recognize the line. For example, placing a period at the
                  end of response can fix the bug.
                  {1}{Some Question}{Some Question}{#}{}{}{}{}{}{}{}{}{}
                  {2}{A. }{1. }{10}{IsFollower("E")    }{}{}{}{}{}{}{}{}
                  {3}{B. }{2. }{20}{IsFollower("Lily") }{}{}{}{}{}{}{}{}
                  {4}{C. }{3. }{30}{IsFollower("VV")   }{}{}{}{}{}{}{}{}
                  {5}{D. }{4. }{40}{IsFollower("Knox") }{}{}{}{}{}{}{}{}
    V > > > > Dialog Audio Synchronization
    V.1 DLG, VCD and LIP Files
      So you make your dialog file and text appears on the screen when you begin a
      conversation with your game entity (be it a person or a telephone). But how
      do you make it actually speak?
      In reality, the dialog engine involves 3 files:
          DLG : DLG files are discussed in the previous section. They link to
                embedded entities and thus invoke the dialog engine. They
                coordinate what NPC say and provide the text for the PC
                response choices. When subtitles are turned on, normally
                the text appearing in the DLG file appears for the NPCs as
          VCD : VCD files are general purpose sequence and synchronization files.
                They are used by several VTMB game components including cut scenes,
                animations and dialogs. They can do almost anything, but in
                regards to dialogs, they are mostly used to specify what audio file
                plays when an NPC makes a statement.
          LIP : Lip files break out how to move the mouth as the associated mp3 is
                playing audio. They also provides subtitles when the player is not
                interacting with the dialog engine. (This is most common during
                cut scenes that involve spoken audio. The introduction is a good
      DLG files implicitly look for VCD files based on their file path.
      Suppose the dialog file is located at:
          <VTMB DIR>/Vampire/dlg/goo/foo.dlg
      The dialog engine will look for VCD files under the directory:
          <VTMB DIR>/Vampire/sound/character/dlg/goo/foo/
      Furthermore, if the dialog engine is displaying an NPC statement at line
      10 of foo.dlg, it will specifically look for the file :
          <VTMB DIR>/Vampire/sound/character/dlg/goo/foo/line10_col_e.vcd
      Hopefully the file paths are obvious, but just in case I will break it
          An Embedded entity links to the file "dlg/goo/foo.dlg".
          The game engine will never look for files outside the
          Vampire directory. For this reason, "Vampire/" is considered
          the BASE DIRECTORY for dialog files and is not included in
          the derived search path.
          After the embedded entity invokes the game engine, the game engine
          searches for a VCD file under "/Vampire/sound/character/".  So in
          this case,  "/Vampire/sound/character/" is considered the BASE
          DIRECTORY for the dialog engine.
       The VCD file name will follow the pattern:
          <index>   : Line number that the NPC response appears on in the
                      corresponding .dlg file. By line number I mean the number
                      that appears in the first column of the line, NOT the
                      physical distance from the top of the file.
          <speaker> : Has several possible values:
                      e : everyone/default
                      f : female (if PC is female)
                      n : nosferatu (if PC is nosferatu)
                      In practice, only the 3 above are ever used (though
                      the engine may support more)
        The dialog engine will not actually look for a LIP file directly.
        If a VCD file is found, it looks for a LIP file only if the
        VCD has a speak event, and then the name of the lip file is based
        on the name of the audio file and not on the name of the dialog file.
        What this means is, you can add new spoken NPC statements to the game by
        simply making a new line number in the DLG fle and creating a corresponding
        VCD file. If the VCD file points to existing NPC audio, you wont have to
        include the audio (mp3) or the lip file with your mod. This is handy to
        know as it can help to keep your mod size down.
    V.2 VCD Internals
      As mentioned earlier, VCD files provide general sequence and synchronization
      capabilities. There is A LOT that could be said about these files. However,
      all we care about right now is how they help us with dialogs. What is the
      minimum that you have to do to get audio to play?
      The first line of a VCD file identifies an actor block.
          actor "Vandal"
      The actor is the NAME of the in game entity that the VCD data will be applied
      to. This is important. The audio that we set up will play at the location of
      the entity named "Vandal".  However, if the entities name that you are
      talking to is not Vandal, no audio will play. Another problem that can happen
      is if there is more than 1 entity on the map with the same name. The engine
      will play the audio at the first entity it comes across, which may or may not
      be the one standing in front of you.
      The VCD files target actor is hard coded into the VCD file and can not be
      changed at runtime. Luckily, you CAN rename entities at runtime using the
      SetName() command.
      Within the actor block are many different channels. Channels are groups of
      events that all start at the same time and execute simultaneously. VCD files
      support numerous channels, but the main one we are concerned with here is
      creating a channel with a speak event. The syntax looks like so:
          actor "Vandal"
            channel "My unique channel name"
              event speak "My unique event name"
                time 0.000000 14.461179
                param "character/dlg/santa monica/vandal/line551_col_e.wav"
                param2 "70dB"
      The text after channel and event speak is arbitrary. It is whatever you want
      to call the channel. If you wish to stick with game conventions, any channel
      with a speak event is called "Speech" and NPC speak events are called: "NPC
          time   : When to start and stop within the associated sound file. If you
                   want to use a small inner sound sample from another existing
                   sentence, you can specify the start/stop range here without
                   having to bloat your mod with a new mp3 file.
                   You can also use the time range to shave time off a slightly
                   unsynchronized audio file without bloating the upload with large
                   audio files.
          param  : In the case of Speech, the event parameter is the name of a wav
                   file. YOU ALWAYS SPECIFY A FILE WITH A >WAV EXTENSION. If an mp3
                   file is detected in the target directory, it will be used in the
                   wav files place,  but if you specify mp3, it will not work.
          param2 : The volume level of the sound as it plays.
          fixedlength : I have no idea what this is or why it is there (how could
                        audio not be fixed length?). Still. it is there in almost
                        all the VCD files, so we go with the flow.
      You can also set up additional channels for executing gestures or facial
      animations on the entity while the audio is playing.
          channel "Gestures"
            event gesture "A little something extra"
              time 0.000000 14.666667
              param "ACT_CONVERSE_NORMAL_TALK"
          channel "Expressions"
            event expression "A smiling finish"
              time 12.000000 14.666667
              param "vandal"
              param2 "Joy"
                1.0000 0.0000
          Note that expressions and Gestures stop when the VCD is finished
          "playing". If you want an expression/gesture to "stick" (angry woman with
          arms crossed for example), you will want to add SetDisposition to the 6th
          column of the DLG line. See the sections below for more information on
          gestures, expressions and dispositions.
      You can also use channels for altering the volume of the audio to create
      inflection or correct audio issues without having to redistribute the audio
      files. (Of course if you are distributing the audio for the first time, you
      should try to get it right so that alterations are not needed).
          channel "Speech Triggers"
            event loud "Get louder here"
              time 10.110000 10.240000
              param "0.130"
            event loud " Get louder here as well"
              time 10.320000 10.429999
              param "0.110"
      You will occasionally see a bonerename parameter at the end of the actor
      block. I'm not certain why this is, but I suspect that some sequences or
      animations may rename bones for their animation and the bonerename is added
      to vcd files to be certain that the bones are called what the animation
      expects them to be. If you see bonerename in one of the characters existing
      vcd files, I recommend doing it as well in your vcd file. And if you don't
      see it in the characters existing vcd files, you probably don't need to do it
      in your files either.
          actor "Vandal"
            bonerename "Bip01" "Bip01"
    V.3 LIP Internals
      As mentioned in part A above, the LIP file that gets loaded is based on the
      name of the wav file that the speak event is associated with. To keep life
      simple we always place the VCD, LIP and MP3 files into the same directory
      together. (and name them with the same convention). This convention is used
      by the main quest and thus is probably a good idea if you want to keep your
      mod code maintainable.
      Here is a small example lip file: I have spaced things for easy reading, but
      in reality you SHOULD NOT add scope spacing.
          |VERSION 1.2                                         |
          |PLAINTEXT                                           |
          |{                                                   |
          |    "Whoa"                                          |
          |}                                                   |
          |WORDS                                               |
          |{                                                   |
          |    WORD Whoa 0.000 1.000                           |
          |    {                                               |
          |        119 w 0.000 0.250 1.000 0                   |
          |        652 ah 0.250 0.750 1.000 0                  |
          |        596 ao 0.750 1.000 1.000 0                  |
          |    }                                               |
          |}                                                   |
          |EMPHASIS                                            |
          |{                                                   |
          |}                                                   |
          |CLOSECAPTION                                        |
          |{                                                   |
          |    english                                         |
          |    {                                               |
          |        PHRASE unicode 12 " W h o a "  0.000 1.000  |
          |    }                                               |
          |}                                                   |
          |OPTIONS                                             |
          |{                                                   |
          |    voice_duck 1                                    |
          |    speaker_name Neo                                |
          |}                                                   |
          A summary of the sentence, likely copied from the dialog file. The
          reality is that the contents of PLAINTEXT are completely arbitrary and
          have no impact on the game at all. The Plaintext block doesn't get used
          by anything nor does it need to match the WORDS block or the
          CLOSECAPTION block. (Though it is convenient when it does).
      WORDS :
          A breakdown of how the mouth moves with the scene. The text that follows
          the WORD definition doesn't have to match anything (PLAINTEXT OR
          CLOSECAPTIONING), however it normally does in practice to help keep the
          file maintainable.
          Each word is described using one of several dozen mouth pose aliases with
          timing info.
              119 w 0.000 0.250 1.000 0
          The first 2 elements describe the mouth pose. At the time of this writing
          (version 1.0), I do not have a comprehensive list of mouth poses.
          However, they appear to be global and you can use words\mouth poses said
          by any model on any other model.
          The third and fourth element are your start and stop time.
          I'm not certain what the last 2 numbers are, but some dialogs have a zero
          at the end and some dialogs do not. I find that the presence of the zero
          tends to affect the articulation emphasis of the models mouth. I have
          also found when copying and pasting words from various dialog files that
          mixing and matching lines that end with 0 and lines that don't end with
          zero will normally crash the game at runtime. You can remedy this by
          making them all the same.
          Finally, if a dialog is crashing, I found that often times removing or
          adding the zero to the end of the line will stop the crash. (if it had a
          0, remove or if it didn't have a zero, add).
          My best guess is that the last 2 numbers are an event_ramp. IE: how
          fast/slow the mouth slides into and out of the pose. When the 0 isn't
          there, it likely takes on a default value.
          The closecaption block actually does get used. However, it is ONLY used
          when the audio is part of a cut scene. If the lip/audio is being executed
          as a result of an NPC dialog, the NPC Statement within the DLG file takes
          priority over the closecaption block.
          As you can see, the CLOSECAPTION block contains a Unicode phrase
          including string length and time signatures for when it should appear.
          The most important thing to mention here is the Unicode string itself. It
          may appear that the Unicode is simply a normal string with spaces between
          the characters. But in reality, the spaces are null characters.
          When python prints a string, it shows non-printables using their
          escaped ASCII values. So from python the command:
              >>> str('"Whoa"').encode("utf-16")[2:]
               ** NOTICE that the double quotes are also Unicode **
          however, in Word or notepad, the string appears as:
              " W h o a "
         To make matters worse, even once you understand what is really there, most
         text editors wont let you insert a null character into your text.
         The good news is that you don't NEED close captioning for 95% of the game
         text. If you know for certain that your audio is intended to support a DLG
         conversation, then I recommend that you leave the area blank:
         If you ARE creating audio for a cut scene (or you are obsessive), you have
         two options. You can use a Hex Editor, which will allow you to see and
         insert the null characters, or you can use my lipedit utility.
         If you downloaded the zip version of this guide, a file called
         "lipedit.py" should be under the tools directory.
         Before running the script, prepare the lip file with a non-Unicode
             PHRASE unicode "Whoa" 0.000 1.000
             NOTE : No indentation and no phrase length. However, the timing info
                    is present.
         Once the lip file is prepped, use Explorer to find the lipedit.py script,
         right click it and Select "Edit with IDLE"
             ** If you do not see "Edit with IDLE", then you need to install
                python 2.1.2. (See I.3 - Standard Tools)
         Two windows will pop up. CLOSE the one that contains the source code.
         Now within the empty python window type:
         >>> import lipedit.py
         >>> lipedit.fix('C:\Path\input.lip','C:\Path\output.lip')
         Obviously you should replace the path info with the full absolute path of
         your input and output lip files.
         This will read in, parse and update the unfinished Unicode block,
         including updating the character count.
      OPTIONS :
          speaker_name : The name that the subtitle system will place next to
                         spoken text during a cut scene if subtitles are turned
                         on. It does NOT have to actually match the name of the
                         entity. (hence why it is "optional")
          voice_duck   : ??? - No idea, but it is present in all the lip files,
                         so I include it.
    V.4 Creating Custom Audio
      This is a little outside the scope of this tutorial, but why not.
      A) Tools I used:
        - Python 2.1.2 : (if you haven't already installed it)
        - WinAmp : (Don't use media player. It locks the files)
        - CoolEdit 96 : There are a plethora of other sound editing tools. This
                        just happens to be my favorite. Simple to use and gets the
                        job done without too many extras.
        - DbPowerAmp : Mp3 to wave/wave to mp3 conversion (I use release 10)
                NOTE : VTMB mp3 audio is 44100Hz Mono at 64Kbps, constant bitrate.
      B) Full Audio or Partial Audio?
          Having no audio at all is better than having bad audio. Even if the
          script is good, bad audio will detract from the players ability to use
          their imagination. If the player is speaking to a sexy model but it
          sounds like a dude speaking in his falsetto, I don’t care what the girl
          is saying, the person playing the game wont be able to get into it.
          A nice middle of the road strategy that I have seen: Have the first few
          words spoken by the character, but not the whole sentence. Most people
          have enough imagination to carry out the rest of the sentence with the
          established voice.
              IE: "Yes? How may I help you?"
              With just the word "Yes" being spoken at the beginning.
         This strategy will save you hours, days, if not weeks and months of dialog
         development time. It will also give you more freedom in designing your
         dialogs. Only the opening line even needs audio. Secondary lines dont need
         *** And if you use VCD files to point to segments of existing audio, you
             will decrease the size of your mod as you wont be including full
         There is a catch. If a line has audio, it normally doesn't display. So to
         get your hybrid lines to display you need to activate subtitles.
         I find the best way to do this is to direct the dialog engine to an
         intermediate line with "..." (that has no associated audio).  This will
         activate the subtitles. Once subtitles are activated within a dialog, they
         stay on till the end of the dialog. You can then redirect to the real line
         with your segmented audio.
         {12}{Yes, what... }{Yes, what... }{#}{}{}{}{}{}{}{}{}{}
         {13}{Response 1   }{Response 1}{}{}{}{}{}{}{}{}{}{}
         {14}{Response 2   }{Response 1 }{#}{}{}{}{}{}{}{}{}{}
         {25}{(STARTING CONDITION)}{ }{10}{1 }{}{}{}{}{}{}{}{}
      B) Conversation Design
          Normally when designing dialog for a game or mod, you would lock yourself
          in a room with a whiteboard or at least a lot of paper and brainstorm on
          what should be said by who and when... And in time you develop your
          scripts. Then you would send your scripts off to a recording studio to be
          spoken, and recorded by professional actors.
          However, most mod developers don’t have the luxury of some things like
          funding.  Thus, many people will be looking to make use of existing audio
          and animation data.
          The MAIN difference is how you go about designing your dialogs. Instead
          of designing a dialog and then having it recorded, you listen to existing
          audio with a particular conversation or even just a moment in mind. You
          let the existing material guide you. This holds true whether you use a
          hybrid or a full audio approach. The material will provide the
          brainstorming. In fact you may not even know how you are going to get
          from point A to point B, but after hearing a few usable sound bytes, the
          ideas start to form.
          It is frustrating for people used to being in full control of their
          conversations, but quality wise, building on top of what is there and
          within its context is generally best.
      C) Breaking out Sound Bytes
        Start by finding the target characters sound files. After you extract the
        .vpk files. Normally they are found somewhere under :
            <VTMB INSTALLATION>/Vampire/sound/character/
        Copy all associated files (mp3, lip and vcd) to a working directory. Then
        uncompress all the mp3 audio as wav files and delete the mp3 files.
        If you wish, you can create a single text file with all the spoken text.
        The lip files contain the sentences. You can do  this the hard way (by
        hand) or if you have installed cygwin, you can do it the easy way:
          - Start cygwin,
          - Use "cd" to change directory to the working directory
              ( /cygdrive/c/... )
          - from the working directory type:
            $ for f in *.lip ; do echo $f; sed –n 4p $f; done > compiled.txt
        compiled.txt will be created with all the spoken text.
        (Be certain to open compiled.txt with WordPad the first time you open it)
        By my 3rd conversation, I stopped bothering with the text files because I
        came to realize that word searches rarely helped me as they didn't tell me
        anything about the tonality, the speed, the emotion.  What was more
        effective was opening each wav file up and trimming out re-usable, stand
        alone words and phrases. I used the file name to help describe what the
        audio was. I would also label the line number and the trim mark in the
        file name:
        This will normally take an entire evening.
        Now from a single directory, you could double click on files and see if the
        tonality is correct for certain combinations of words. This will allow you
        to form new sentences more effectively. Winamp allows you to queue things
        up easily by CTRL + Clicking wav files.So you can experiment and see how
        the end product might sound before you spend time appending everything
        together with CoolEdit.
        If you need a specific word that doesn't exist, you can often piece it
        together by using 2 different words with similar syllables.
            Example : subterfuge + admit = submit
        But occasionally, you just have to admit defeat and try to think of a
        different word.
      D) Re-Composition
        This is the hard part. As I mentioned before, when I trimmed the files, I
        kept track of the trim marks. CoolEdit does a good job of showing you the
        selected area in the bottom right corner of the app:
        [ -_--_--################-___-_- ]
                  ^              ^
                  |              |
                2.345          6.789
        Each wav file has a lip file with data in it that tells the engine how to
        move the mouth with the words. Problem is, the time signatures in the lip
        files will not match up with the timing of your new sentence. If I trimmed
        the example above and I wanted to START a sentence with the word that used
        to reside at 2.345, I would need to subtract 2.345 from all the time
        signatures within the lip file.
        And, I actually did that for my first conversation. Took 3 days to make 3
        So, I decided to make a python script to do it for me. It is named
        lipedit.py (You may recognize this name if you have already read the
        dialog section). The script comes with the zip version of this Guide and
        should be located in the tools/ directory.
        To use it, you will have to have installed python (See standard Tools in
        Section I). Right Clip lipedit.py, chose "Edit with idle". Two Python
        windows will pop up. Close the one with the source code in it. In the
        (mostly emtpy) window type:
        >>> import lipedit
        >>> lipedit.fix("C:\\input\\file.lip","C:\\output\\file.lip",-2.345)
        lipedit uses regular expressions to scan and fix the values.
        Use Case Scenario:
          Typically, I would use CoolEdit to see at what time the word should be
          spoken. Lets say the word "Help" starts at the 5.0 time signature in
          my wav file.
          Next I look at the filename that help came from:
          Then I would open up line141_col_e.lip and search for the instance of
          the  Word "help" around the 0.932.
          WORD help .928 1.115
          113 h  .915 1.010 1.000 0
          213 e 1.010 1.050 1.000 0
          413 l 1.050 1.100 1.000 0
          513 p 1.100 1.115 1.000 0
          I would note that the first ACTUAL SYLLABLE of help begins at .915
          So to make "help" appear at 5.0, I need to add 4.085: (yes, you will
          still need a calculator).
          >>> lipedit.fix('C:\in\line141_col_e.lip','C:\output\help.lip',4.085)
          Now I open up help.lip and past the correct time signature for help
          into a new lip file that I am creating for the sentence.
        Note that the python script ONLY FIXES the time signatures. You still have
        to go in, copy out the words (with the corrected time signatures) into a
        new lip file and update the lip file with the text that should appear to
        the user in the subtitles.
        If this all sounds crazy, then go look at a lip file and then come back
        here and you will know what I mean.
        The last step is the vcd file. The easiest thing to do is simply correct
        the file name/path, the audio length and then remove expressions, etc from
        the rest of the file. Of course, you are also free to throw stuff in. Just
        remember that any existing material was thrown off by the trim. And I
        didn't make a py script to autofix vcd files.
        It is a tedious process. Even with the help of the lip timing script, once
        you get into the flow, you only average about 1 lip file every 45
        minutes, and that is after you have pieced the wav files together (which
        may take you days).
        Alternatively, if you have the means to record your own audio, you can use
        that.  However, your biggest hurdle will be making realistic LIP files. If
        you DO decide to be brave and record your own audio, you may want to
        generate text files of all the conversations. Then you can search for a
        word that you say and use the script to correct the timing (maybe). Or you
        could fudge it by hand. If I was piecing a line together word by word from
        scratch, I  probably wouldn't bother with the python script.
        Even if you cant find an exact word, something like it will normally do.
        For example, when muted, you probably cant tell if a models lips are saying
        devious or delicious.
    VI  > > > >  Animating NPCs with Python
       The animation for NPCs is divided up into 3 categories: skeletal animations
       Facial expressions and Lip synching.
       Once you understand what animations and expressions are available to you,
       there are several ways of incorporating them into the game:
       1) Direct (SetAnimation)
       2) Dispositions
       3) Gestures (Interesting Places)
       4) Schedules
       1) Scripted Sequences
       2) Choreographed scenes
    VI.1  > > > >  Skeletal Animations
      Models have a skeleton and a hull. The skeletons attach to the hull and
      control movement of the hull. (The hull is normally painted with a skin).
      Being that models are so different, it should not be a surprise that
      skeletal animations are NOT globally standardized. For example, how could
      stubs the zombie with no arms and no legs execute a "standard" animation that
      involves jumping into the air.
      The good news is that most HUMAN LIKE NPCS (2 arms, 2 legs and a head)share a
      common skeleton. Thus, there is a set of "standard" animations. This is made
      possible because the MDL format allows models that share the same base
      skeleton to also share animations by linking to an external MDL file were
      common animations are defined.
      The vast majority of Human-Like NPCS link to "npc_allsequences.mdl". This
      is defined twice, once for male models and once for female models.
      in both circumstance however, the master animation file further breaks out
      the common animations into separate animation files:
      npc_allsequences.mdl :
         - linkto ->  shared/.../animal_feed.mdl
         - linkto ->  shared/.../baseball.mdl
         - linkto ->  shared/.../bushhook.mdl
         - linkto ->  shared/.../claws.mdl
         - linkto ->  shared/.../finished_moves.mdl
         - linkto ->  shared/.../fists.mdl
         - linkto ->  shared/.../forced_feed.mdl
         - linkto ->  shared/.../katana.mdl
         - linkto ->  shared/.../knife.mdl
         - linkto ->  shared/.../meleeshared_onehand.mdl
         - linkto ->  shared/.../meleeshared_twohand.mdl
         - linkto ->  shared/.../misc.mdl
         - linkto ->  shared/.../move_and_ranged.mdl
         - linkto ->  shared/.../seductive_feed.mdl
         - linkto ->  shared/.../sherifsword.mdl
         - linkto ->  shared/.../sledgehammer.mdl
         - linkto ->  shared/.../stake.mld
         - linkto ->  shared/.../tireiron.mdl
         - linkto ->  shared/.../zombie_feed.mdl
      If you take the time to open up each of these files with VPKTool Model Tool
      tab, you can see all the animation names listed in the info window at the
      bottom of the tool. I have taken the liberty of documenting these in Appendix
      Raw animations are generally not applied DIRECTLY within the game. They
      are used by internal mechanisms such as the combat system, gestures,
      and schedules and by embedded elements such as scripted_sequence.
      The only time they are used directly within the game is when you have a
      "prop_dynamic" object. For example, in the strip club, there
      are dancers up on stage that you can’t approach. They are in fact not
      npcs but "prop_dynamic" objects with an animation set.
      You can create the illusion of applying an animation to an npc by
      Hiding the npc (set the model to models/null.mdl), dynamically
      Create a prop_dynamic where they are standing, and then set the
      Model/Animation.  The downside of applying animations in this
      manner is that you have no control over the model’s facial
      expressions. This may or may not be a big deal for you.
        _EntCreate = __main__.CreateEntityNoSpawn
        _EntSpawn  = __main__.CallEntitySpawn
        npc = __main__.FindEntityByName("targetNPCName")
        e=_EntCreate ("prop_dynamic", npc.GetOrigin(),npc.GetAngles())
        e.SetName("prop_" + npc.GetName)
      Some models contain additional internal animations that are specific to that
      model. For example, models/character/npc/common/stripper/Stripper3.mdl
      contains several animations that only that specific model will perform.
      Other models link to additional external MDL files for animations. For
      example, models/character/npc/common/lotusblossom_girl/lotusblossom_girl.mdl
      links to character/shared/female/stripper.mdl in addition to the common
    VI.2  > > > >  Facial Expressions
      Facial Expressions are basically animations meant specifically for an NPCs
      face. Because faces are more unique than the body, they get special
      attention.  Each model defines their own set of supported expressions. You
      can browse the expressions for a given model\character under the
      "Vampire\expressions" directory.
      95% of the models just implement the standard set of expressions (located
      in Vampire\expressions\expressions.txt). The "common" expressions are
      as follows:
        "Neutral"          "Nearly Crying"              "Nearly Crying_No Deform"
        "Joy"              "Melancholy Smile"           "Meloncholy_NoDeform"
        "Fear"             "Confused"                   "Disgust_NoDeform"
        "Very Frightened"  "Disgust"                    "Sad_NoDeform"
        "Sly Smile"        "Apathy"                     "Fear_NoDeform"
        "Flirtatious"      "Lowered Both"               "Sly Smile_NoDeform"
        "Anger"            "Raised Both"                "Confused_NoDeform"
        "Mad"              "Raised Right"               "Flirtatious_NoDeform"
        "Enraged"          "Raised Left"                "Knockback"
        "Sad"              "Lowered Right"              "Anger_No Deform "
        "Miserable"        "Lowered Left"
      In the case of VV, her model supports additional expressions.
      - I found when executing the SetExpression() method, the next if statement
        (wherever it executed from) would throw an exception saying function
        expects 7 parameters. You can avoid breaking later code by
        preemptively calling if from within a try-catch block after using
        the SetExpression method.
        def SetExpression(npc, expression):
            try: npc.SetExpression(expression)
            except:  npc.SetExpression(expression)
            try: if data=="": return
            except: pass
      - Model specific animations will only work on the original model. If the
        model is a clone of the original (ie: someone copied vv.mdl to vv2.mdl so
        that they could link to a different outfit), the vv specific expressions
        will not work on the clone. The expressions will only work on the original
    VI.3  > > > >  Dispositions
      A disposition is a combination of Body animation and Facial Expression.
      However, dispositions can not include just any Animation. They are limited
      to the STANCE animations defined in stances.mdl.
      Dispositions are mostly used to emphasis the facial expression with
      additional body language. For example, if someone is mad at you, they might
      place a hand on the hip or cross their arms. If they are trying to seduce you
      they may lay down on a bed in addition to the sexy smirk they throw at you.
      Like expressions, MOST dispositions are common. However, there are a few
      Dispositions that are meant for specific characters.
      Common Dispositions:
      When setting a disposition, you specify a name and level. The name
      corresponds to the body animation and the level corresponds to the facial
          Disposition       Levels
          Neutral           [1]
          Anger             [1,2,3]
          Joy               [1,2,3]
          Sad               [1,2,3]
          Fear              [1,2]
          Disgust           [1]
          Apathy            [1]
          Flirtatious       [1]
          Confused          [1]
          Lay               [1,2,3,4]
          Damaged           [1]
          Dead              [1]
          Sitting           [1]
          Bartender         [1,2]
          BehindBack        [1]
      Unique Dispositions:
          Disposition       Levels
          Therese           [1,2,3] -> Therese Only
          Lily              [1,2]   -> Lily Only
          ChairDamaged      [1,2]   -> Lily Only
          PrinceSitting     [1]     -> Chunk and Lacroix Only
      Fortunately, all NPCs have a method on them called SetDisposition which makes
      Using dispositions much easier than animations.
    VI.4  > > > >  Schedules and ScriptedDisciplines
      A schedule is a tiny program that executes on an NPC. Every NPC has a
      Schedule assigned to it. When you cast a spell in the game, under the hood,
      the game assigns your target a schedule that results in the spells execution.
      However schedules are not just used for spells. When you tell an NPC to
      follow you, they execute a special schedule that causes them to follow you
      around the map.
      Most NPCs execute the common schedule SCHED_TROIKA_IDLE. This schedule
      includes a laundry list of tasks such as scanning for enemies, the pc,
      looking at the player if they are near, presenting a dialog icon if
      the pc gets close enough, etc.
      As you can imagine, changing an NPC’s schedule can cause an animation to
      happen. However, it should be noted that schedules are not JUST animations.
      For example, setting an NPC’s schedule to SCHED_TROIKA_D_BLOODBOIL_EXPLODE
      will show the very cool blood boil explosion animation. It will also kill
      the npc in the process.
      FROM : vdata/system/disciplinetgt_xxx
      SCHED_TROIKA_D_PESTILENCE"  // Note: Dies at the end!  (Dmg_Health 100%)
      * You can find other schedules by using the "picker" console command from in
      You can accomplish the same thing by using SetScriptedDiscipline()
        vv.SetScriptedDiscipline("dominate 1")
    VI.5  > > > >  Gestures and intersting_place
      Interesting places are objects. You can think of them as phone-booth sized
      invisible boxes on a map that draw nearby NPCs to them like a magnet. When
      the NPC enters the box, they perform whatever action the box is configured
      Interesting places generally use gestures to define/refine the activities
      that may occur when a user enters the box. Gestures map to animations,
      however while it is safe to say that every Gesture has a corresponding
      animation, it is not safe to say that every animation has a corresponding
      (SAMPLE) FROM : Vampire/vdata/system/interestingplacetypelist.txt
      (See Appendix I for more)
      All NPC’s have a SetGesture() method on them. You can pass in one of the
      ACT_<gesture> strings, or you can pass in an animation name.
        vv.SetGesture ("ACT_COUCH_SIT_INTO")
        vv.SetGesture ("ACT_COUCH_SIT_OUTOF")
        vv.SetGesture ("CouchTV_Into")
        vv.SetGesture ("CouchTV_outof")
      Single shot animations and gestures will execute only once and then stop.
      However looping animations and gestures will continue to execute over and
      over again as part of the npc’s schedule. Furthermore, the looping
      IDLE_DISPOSITION gesture is hard coded into all the SCHED_TROIKA_IDLE
      schedule so that an npc will always alternate between the idle action and the
      looping gesture you assign them.
      This is very annoying and as a result, I recommend avoiding any looping
      gestures or animations with SetGesture.
    VI.6  > > > >  scripted_sequence and logic_choreographed_scene
      Both of these entities allow you to apply an animation to an entity on
      the map. Unlike the limited pure python solutions discussed above, these
      entities must be embedded into the map you wish to execute the animation on
      and hooked up to the entity by name.
      A) scripted_sequence
          Scripted Sequences are used to execute animations and movements on map
          characeters. By default, they execute once and then self-delete. You
          can override this behavior by setting some of the spawn flags:
             bit  value   Meaning
              1     1
              2     2
              3     4      Persistent
              4     8
              5     16     Start Enabled
              6     32
              7     64
              8     128
              9     256     Enable looping Post Idle Animation
             10     512
             11     1024
             12     2048
             13     4096
             14     8192
             15     16384
             16     32768
             Using bits : So a spawn flag has 16 options : 0000000000000000
             They are either true or false. To enable an option, you set the bit
             to 1. When you are finished, you convert the binary value to decimal.
             The right most value of the binary number corresponds to bit 1.
                 To enable bit 3,5 and 9 = 100010100
                     Calculator -> View -> Scientific, check "[*] Bin".
                     Enter the number above and then hit "[*] Dec"
                     Value = 276.
             Alternatively, you can add the values up from the value colum of those
             bits you wish to enable.
             Persistent + Post Idle Animation Enabled = 4 + 256 = 260
          Example: Have VV execute a standard animation in your apartment. The
          following entity must be embedded into the apartment:
              We use spawn flag 260 so that the animation will loop.
              "classname" "scripted_sequence"
              "targetname" "vv_mesmerized"
              "spawnflags" "260"
              "m_flRadius" "5"
              "m_flRepeat" "0"
              "m_fMoveTo" "0"
              "m_iszEntity" "vv"
              "m_iszPlay" "dance01"
              "m_iszPostIdle" "dance01"
              "origin" "-1768.03 -2646.97 144.03"
              "angles" "0 165 0"
              ] import custom
              ] vv=custom.mySpawnNPC("vv")
              ] seq=FindEntityByName("vv_mesmerized")
              ] seq.SetOrigin(vv.GetOrigin())
              ] seq.BeginSequence()
          Option Details:
              "m_flRadius"- Search radius for entities. Depending on the spawn
                            flag, it may or may not care if the Entity matches the
                            name of the m_iszEntity property.
              "m_iszIdle" - If set, this is the animation that plays PRIOR to
                            calling BeginSequence. Only has affect if StartEnabled
                            is true.
              "m_iszPlay" - When you call BeginSequence, this is the animation that
          "m_iszPostIdle" - Animaiton that plays after m_iszPlay.
              "m_fMoveTo" - 0 : entity plays animations where it is.
                            1 : entity walks to scripted_sequence, then starts
                            2 : entity runs to scripted_sequence, then starts
                            3 : Walk to scripted_sequence, Walk back when finished
                            4 : Walk to scripted_sequence, Teleport back on finish
      B) logic_choreographed_scene
          Some MDL files contain skeletal animations meant for as many as 4 NPC
          models. To use these animations, typically the game uses the
          logic_choreographed_scene entity to identify the animation and the models
          to execute the animations on.
          For example, the opening scene of the game uses a scene with 4 npcs to
          have your PC and their sire kneel in front of the theater.
          logic_choreographed_scene is not limited to multi-actor animations. You
          can in fact use them to apply any animation from any mdl to any other
          entity model.
          Example: Have VV execute the stripper lap dance in your apartment, even
                   though it is not one of the standard animations:
              "classname" "logic_choreographed_scene"
              "targetname" "mylapdance"
              "origin" "-1768.03 -2602.09 144.03"
              "angles" "0 300 0"
              "position_start" "1"
              "position_end" "3"
              "hide_ents" "0"
              "force_lod" "0"
              "target1" "noone"
              "target2" "vv"
              "BaseAnim" "models/cinematic/Hollywood/Vesuvius/Lap_danceGroup_4.mdl"
              "SceneFile" "sound/cinematic/Hollywood/Vesuvius/custom.vcd"
              "OnCompletion" " mylapdance,Start,,0,-1,,"
              ** The actual targets of the animation are controlled by the
                 SceneFile. The internal target[x] attributes are ignored and used
                 mostly as a local place holder so you don’t have to go open the
                 scene file to figure out what to name your targets.
          The Corresponding .vcd file would be updated as follows:
            |Filename = [<vampire root>/sound/cinematic/.../custom.vcd]          |
            |actor "noone"                                                       |
            |{                                                                   |
            |  channel "Anim"                                                    |
            |  {                                                                 |
            |    event sequence "Lap_dance"                                      |
            |    {                                                               |
            |      time 0.000000 3600                                            |
            |      param "entire_scene"                                          |
            |    }                                                               |
            |  }                                                                 |
            |  bonerename "Bip02" "Bip01"                                        |
            |}                                                                   |
            |actor "vv"                                                          |
            |{                                                                   |
            |  channel "Anim"                                                    |
            |  {                                                                 |
            |    event sequence "Lap_dance"                                      |
            |    {                                                               |
            |      time 0.000000 3600                                            |
            |      param "entire_scene"                                          |
            |    }                                                               |
            |  }                                                                 |
            |  bonerename "Bip01" "Bip01"                                        |
            |}                                                                   |
            |fps 60                                                              |
            |snap off                                                            |
      To run the animation, you would create a vv model named "vv", a null model
      named "noone" and then call the Start() method on the embedded entity.
      ] import custom
      ] vv=custom.mySpawnNPC("vv")
      ] noone=custom.mySpawnNPC("noone","models/null.mdl")
      ] scene=FindEntityByName("mylapdance")
      ] scene.Start()
      Since the vv model is a real NPC (and not a prop_dynamic), you can set
      her expression:
      ] custom.SetExpression(vv,"Sly Smile")
    VII.   > > > > Editing Models/Skins
    VII.1 Basics
      Models are composed of several files:
        <modelname>.mdl : Defines the structure of the model along with animation,
                          bounding box, hit box, material, mesh and LOD info.
        <modelname>.vtx : vtx files store hardware optimized material, skinning and
                          triangle strip/fan information for each Level Of Detail
                          (LOD) of each mesh in the MDL. They come in several names
                          for backwards compatibility with older hardware. (DirectX
        <modelname.phy> : [optional] contains jointed ragdoll collision model.
        <skinname>.vmt  : meta data file that "redirects" to actual texture.
        <skinname>.ttz  : ttz and tth work together to define the models
        <skinname>.tth    texture.  When working with skins, you must
                          maintain both.
        Additionally, MDL files may link to other MDL files internally for
        shared animations.
    VII.2 MDL File Details
      MDL Files contain a lot of information. You can view more of this information
      using VPKTool. Use the Model Tools tab to select a .mdl file and open
      1) Texture Search Paths : Where to search for the VMT files.
      2) Texture Names : The name of the VMT files. It is important to note that
         MDL files do not link directly to textures. They link to VMT files. VMT
         files are text based property files that point to the actual textures:
                        ##############################     #######################
                    --> # search/path/TEXTURE1(.vmt) # --> # /full/path/TEXTURE1 #
         #########/     ##############################     #######################
         #  MDL  #
         #########\     ##############################     #######################
                    --> # search/path/TEXTURE2(.vmt) # --> # /full/path/TEXTURE2 #
                        ##############################     #######################
       3) VPKTool has is a window at the bottom that often times goes unnoticed,
          however contains some very cool info if you scroll up.
          Aside from the texture info, it lists the models animations. Most
          Animations come from a shared animations mdl file. Normally:
          However, in addition to this "external" link, the models specific
          animations are also listed. Typically these exist for cut-scenes
          or complex dialogs where the general purpose expression engine wasn't
          good enough.
    VII.3 Working with downloaded Skins
      The instructions below assume you have extracted the contents of all the
      .vpk files somewhere accessible.
      A) Replacing the Original Skin
         To keep things simple, we will start with the typical scenario: you
         Download someone else’s skin from the internet and want to install it
         into the game. For this example, we will use Dark VV:
         Most 3rd party skins REPLACE the existing Skin. This is done by
         Clobbering the original skins vmt, ttz and tth files.
         Following the chart above, the MDL will find the new VMT files (by the
         same name) which point to the new Texture files (by the same name).
         The key here is that the mdl file is unchanged. Thus, when you play the
         game, the new skin will be visible on the original character.
      B) Adding new clothing options to existing NPCs
         Why replace VV’s skin, when you can install an additional outfit? The main
         reason is because normal people wouldn’t know how to use/access the skin.
         However, As a script savy modder armed with this guide, this shouldn’t
         phase you.
         1) Creating the new "outfit" model.
            We start by duplicating the original model. You can do this the hard
            way by renaming each file, or you can do this the easy way by simply
            copying the whole directory to a new directory name. Lets go easy!
            THE MODEL:
            Copy the Original MODEL files (mdl, vtx, phy, etc...):
              FROM:  \Vampire\models\character\npc\unique\downtown\vv\*
              TO  :  \Vampire\models\character\npc\unique\downtown\vv2\*
            Update the Original Model
             OPEN: \Vampire\models\character\npc\unique\downtown\vv2\vv.mdl
             UPDATE: "Texture Search Path", change directory to vv2
             COMMIT ALL CHANGES: When you hit this button, it will prompt you for a
                                 place to save. Save as a new name:
             NOTE: Internally, the MDL file saves its own name. So it is important
                   not to rename the file (using explorer) or even move it to a
                   different directory after you save. If you decide to rename the
                   file, re-open and save again using VPKTool.
            Clean up : Delete Original MDL:
              FROM:  \Vampire\models\character\npc\unique\downtown\vv2\vv.mdl
            THE SKIN:
            Copy MATERIALS:
              FROM:  \Vampire\materials\models\character\npc\unique\downtown\vv
              TO  :  \Vampire\materials\models\character\npc\unique\downtown\vv2
              Zip files downloaded off the internet normally don’t contain all
              required skins. For example, it may update the clothes, but not the
              teeth or hair. Most zip files assume that the original directories
              materials are still present. So we must copy everything over.
            UNZIP SKIN:
              TO  :  \Vampire\materials\models\character\npc\unique\downtown\vv2
              Note that the zip file may contain the full directory path. Be
              Certain to unzip the files directly to the taget directory (vv2 in
              this case). You should be prompted about overwriting existing files.
              Say yes.
            UPDATE VMT(s)
              INSIDE:  \Vampire\materials\models\character\npc\unique\downtown\vv2
              The original author likely expected their textures to be in a
              different directory. So you must open the .vmt files (use notepad)
              and update the paths. In this case, to "vv2".
         2) [Optional] Optimizatized method (uses less disk space)
            The method above is the easy way. The downside is that a lot of
            textures may unnecessarily be duplicated.
            A more efficient method is to extract the downloaded skin to its own
            empty directory. Take note of the textures it updates. Rename them
            (say with a 2 somewhere in the name). Copy the renamed texture files
            to the original materials directory (VV) and update the corresponding
            (and renamed) vmt files to point to the new textures. Now duplicate the
            VV model (and associated vtx files) and rename them, but place within
            the original models directly. Finally, edit the newly named mdl file,
            and only update those textures that came with your download (which you
            should have renamed). This allows you to re-use the unchanged textures
            (like teeth).
         3) Changing Clothes with a Script (from console)
            You can change an NPCs model relatively easily using the SetModel()
            Above, I use the PC as an example, but it works on NPCs as well. Use
            the "picker" console command to get an NPCs instance name, then:
          MDL files DO support multiple skins. An example is:
          If you create this entity and assign it to the variable "cube" you can
          change its skin using the command:
          Cube only requires 1 texture, but the MDL file has 4 textures. When an
          mdl file has more textures than a model needs, FadeToSkin(#) attempts
          to reload the skin starting with an offset that corresponds to #.
          If a model requires 5 textures to map to all of its parts, then all it
          need do to define an additional skin is define 10 internal texture
          links. The function npc.FadeToSkin(1) would offset the starting texture
          accordingly. If there were 15 textures defined, FadeToSkin(2) would
          apply the last 5, etc...
          However, VPKTool does not allow you to ADD textures to the MDL file, so
          there is no way to take advantage of the engines multiple skin support
          using VPKTool alone. There may be a way using more advanced external
          tools, but that is outside the scope of this tutorial.
    VII.4 Editing Skins yourself
      The instructions below assume you have extracted the contents of all the
      .vpk files somewhere accessible. For this example, we will create a WHITE
      business suit for Therese.
      The instructions also assume the installation of the latest Gimp:
      GIMP comes with a DDS plugin already installed that allows you to SAVE as
      DDS. If you use another image editing program, you will need to find a
      DDS plugin or a TGA to DDS stand alone conversion utility from the internet.
      A) Locate the original NPC's outfit:
         Normally the outfit skins are located under :
         <VTMB install dir>\Vampire\materials\models\character\npc
         Example :
     B) Copy all outfit files to a working directory.
        I personally prefer a Desktop accessible directory such as:
     C) Use VPKTool to convert the TTZ files to TGA:
         - Run VPKTool
         - Click on the "Texture Tools" Tab
         - Browse to your working directory
         - Select a TTZ file.
         - Click on the "Convert TTZ to TGA" button.
         - Repeat C steps above for each TTZ file.
     E) Open the File up in Gimp (Or you image editing program of choice)
        In this specific example, we want to edit the files :
        For this example, we will do a simple color inversion. Find the
        "Free Select Tool" on the tool menu and outline the 3
        items in the image that are obviously fabric. If you mess up,
        dont worry. You can "ADD" to the selection by holding down
        shift. Or you can "REMOVE" from the selection by holding down
        Once the 3 fabric areas are selected, from the Menu, select :
        Colors -> Invert
        When you save, specifiy "DDS" as the file format you wish to save in.
          COMPRESSION : DXT5
          [X] Generate mipmaps
        If this is not available (because your not using GIMP) You can save as
        TGA, but you will need to find a TGA to DDS conversion program from the
        Open up the Skirt file and invert the entire image then save in the same
     E) Convert the DDS back into TTZ:
         - Run VPKTool
         - Click on the "Texture Tools" Tab
         - Browse to your working directory for your DDS files.
         - Check the Header Information:
           [X] Hint DXT5
         - Click the "convert DDS to TTZ" button.
         This will create a new TTZ file AND update the local TTH file. You
         must maintain both.
      F) Backup and Copy
         Backup the original files that you edited. (Typically simply rename)
         and then paste the new TTZ /TTH files into the materials directory.
         Now when you see Therese, she will have a WHITE suit on instead of
         a dark brown suit.
    VIII. > > > > Cameras and Cut scenes
        TODO (I didn’t do any camera controls or cut scene work with my mod)
    IX. > > > > Custom Items
    IX.1 Defining Custom items
      Items are defined in:
      I am not going to go into a lot of detail about the item format. Most of the
      time you find an item similar to what you want to add and re-use its
      properties. You can point to any existing mdl file the game has to offer
      for how it looks when it is sitting on the ground.
      A) The Bad News:
          You can not add additional items to the game. What I mean by that is
          the item names were hard coded into the games executable. The directory
          above contains configuration data for all the items, however if you
          simply paste a new item into the directory it will not show up or be
          accessible within the game.
      B) The Good News:
          A lot of items were embedded into the game that are not used. How do you
          know what is used and what isn't? Not an easy question. Personally, I
          install cygwin. Then cd to cygdrive/c/Program.../Vampire and then type:
          grep -Hir <item_name> .
          It takes about 3 min to run and when it is finished it tells me if the
          item is used by the game and where. (It is important that you have
          installed whatever patches you plan on building upon and extracted all
          the meta data out of the map .bsp files before you run the grep).
          Don't pay attention to hits on the .vpk files. What you care about is if
          it is in the metadata of a BSP map file, a python script (.py) or dialog
          file (.dlg).
      C) A few examples:
          These items are unused by the original game:
          You can edit these items, there description, display model, etc...
          However, when embedding them within a map or accessing them from your
          scripting code, you will still have to refer to them by their original
      D) NOTES:
          There are a finite number of such items. Sometimes, adding a new item
          to the game means getting rid of something else. If you are building your
          mod on top of someone else's mod and you wish to add a special item, you
          must be certain that you do not use an item that one of your support mods
          depends on. Note the word "depend". If it is not necessary for the mods
          function, then you could remove the item from the mod so that you can use
          For example, WESP updated the 2 items above and embedded them into the
          game with the 5.6 Patch. However, they are not NEEDED by the game, so you
          could remove them if you needed them so that you could use them yourself.
          Wesp also freed up item_g_wireless_camera_2, item_g_wireless_camera_3 and
          item_g_wireless_camera_4 by changing the associated quest to only require
          1 stackable camera.
          The companion mod which builds on top of Wesp's work, uses
          item_g_wireless_camera_2 and item_g_wireless_camera_3. However, of those
          two items, only the first is NECESSARY for the mods functionality. So
          if you really needed the slots, you could use both of the item slots
          above as well as camera_3 and camera_4.
          These are just examples and some of the considerations you should be
          aware of.
    IX.2 Capturing Item usage events
      The VTMB engine does not provide a nice way to capture events. I will
      discuss 2 approaches here which are work arounds.
      A) Basics : Defining Aliases and Binds
          Throughout this guide I have focused on Python. I have mentioned console
          commands, but generally only when they are needed to accomplish something
          that can't be done from python.  Well this is one of those situations.
          The console supports the concept of aliases. An alias is like a tiny, one
          line program. It can execute console commands or python commands.
              ] alias foo "print 'This is a python command'"
              ] foo
              This is a python command
          The console also supports the concept of key bindings. A key can be bound
          to execute a string, or execute an alias:
              ] bind t " print 'You PRESSED T!'"
              ] bind f "foo"
          If you hide the console, then press t or f and then unhide the console,
          you will see messages printed.
          Finally, python supports the concept of KEYDOWN and KEYUP events through
          the use of "+" or "-" infront of an alias definition.
              ] alias +foo "print 'KEY DOWN!'"
              ] alias -foo "print 'KEY UP!'"
              ] bind f "+foo"
          +foo will execute when the f key goes down and -foo will execute when the
          f key comes up, even though you only bind f to +foo.
      B) Requiring users to setup special cfg values:
          So, one approach to capturing item usage events is to capture the
          attack event and then execute some code to see if you should do
          something special based on the weapon equipped.
            |Filename = [<vampire root>/Vampire/cfg/autoexec.cfg]                |
            | // Required by Mod                                                 |
            | alias u_i_1 "__main__.ScheduleTask(0.0,'OnPlayerAttackStart()')"   |
            | alias u_i_2 "__main__.ScheduleTask(0.0,'OnPlayerAttackEnd()')"     |
            | alias +m_attack "u_i_1;+attack"                                    |
            | alias -m_attack "u_i_2;-attack"                                    |
          Notice the code above uses ScheduleTask. This forks the event off so
          that it returns quickly and prevents any python errors/exceptions from
          breaking the users ability to attack.
            |Filename = [<vampire root>/Vampire/python/vamputils.py]             |
            | ...                                                                |
            | def OnPlayerAttackStart():                                         |
            |     if __main__.FindPlayer().HasWeaponEquipped("item_my_item")     |
            |         print "THEY ARE USING MY EDITED ITEM/WEAPON!\n"            |
            |         # MAKE PC UNSEEN but unable to move (example)              |
            |         __main__.ccmd.notarget=""                                  |
            |         __main__.ccmd.player_immobilize=""                         |
            |                                                                    |
            |                                                                    |
            | def OnPlayerAttackEnd():                                           |
            |     if __main__.FindPlayer().HasWeaponEquipped("item_my_item")     |
            |         print "THEY STOPPED USING MY ITEM/WEAPON!\n"               |
            |         __main__.ccmd.notarget=""                                  |
            |         __main__.ccmd.player_mobilize=""                           |
            |                                                                    |
          The last part is the tricky part. For all of this to work, the USER
          must manually hook up the +m_attack you defined within their config.cfg
          so that your script receives the OnPlayerAttackStart and
          OnPlayerAttackEnd notifications.
            |Filename = [<vampire root>/Vampire/cfg/config.cfg]                  |
            | ...                                                                |
            | bind "MWHEELUP" "invprev"                                          |
            | bind "MOUSE1" "+m_attack" // changed from bind "MOUSE1" "+attack"  |
            | bind "MOUSE2" "vdiscipline_last"                                   |
            | ...
          And this is the dilemma with this solution. It requires a user who is not
          afraid to get their hands dirty with a config.cfg file. Still it works
          and in some ways it is less intrusive since the user KNOWS what you are
      C) AUTO Setup config values:
          Here, we use the same approach as A., however we do a little extra
          leg work so that the user doesn't have to do anything at all. For
          starters, we add a new line to your autoexec.cfg:
            |Filename = [<vampire root>/Vampire/cfg/autoexec.cfg]                |
            | // Required by Mod                                                 |
            | alias execonsole "exec console.cfg"                                |
            | alias u_i_1 "__main__.ScheduleTask(0.0,' OnPlayerAttackStart()')"  |
            | alias u_i_2 "__main__.ScheduleTask(0.0,' OnPlayerAttackEnd()')"    |
            | alias +m_attack "u_i_1;+attack"                                    |
            | alias -m_attack "u_i_2;-attack"                                    |
            The new execonsole alias allows us to write console commands to a file
            and execute them from python.
            The idea is, when the game loads, we fix the attack binding to point
            to our custom binding. Easier said than done. For one thing, this
            involves reading in the config.cfg file, parsing it for "+attack"
            and then sending a command to the game to rebind the associated
            key with "+m_attack". And we must not forget that the player can
            bind multiple keys to +attack (MOUSE1 and the letter "q" for example)
            |Filename = [<vampire root>/Vampire/python/vamputils.py]             |
            | ...                                                                |
            | def OnPlayerAttackStart():                                         |
            | ...                                                                |
            |                                                                    |
            | def OnPlayerAttackEnd():                                           |
            | ...                                                                |
            |                                                                    |
            | def FixAttackBinding():                                            |
            |   data = ''                                                        |
            |   fin = None                                                       |
            |   try:                                                             |
            |     fin = open('Vampire/cfg/config.cfg',"r")                       |
            |     line = fin.readline()                                          |
            |     while line:                                                    |
            |       s = line.rfind('"+attack"')                                  |
            |       if -1 != s:                                                  |
            |         r = s                                                      |
            |         s = line.find(' ')                                         |
            |         data='%sbind %s "+m_attack"\n' % (data,line[s:r].strip())  |
            |       line=fin.readline()                                          |
            |   finally:                                                         |
            |     if fin: fin.close()                                            |
            |                                                                    |
            |   if 0 != len(data):                                               |
            |     cfg=open('Vampire/cfg/console.cfg', 'w')                       |
            |     try: cfg.write(data)                                           |
            |     finally: cfg.close()                                           |
            |     __main__.ccmd.execonsole=""                                    |
            |                                                                    |
            | FixAttackBinding()                                                 |
            In this scenario, the binding is fixed when the game is started. If the
            user changes their config within the game, they would break the item
            until they restarted the game. However, telling a user they have to
            restart their game if they change the config isn't as complicated as
            walking them through editing their config.cfg file.
      D) Discovering what NPC is under the target hair:
          The game doesn't really support this, but here I talk about workarounds.
          There are two workarounds. The easy and the hard work around. The hard
          work around involves computing a range of values that represents a cone
          in the direction that the PC is facing and then grabbing the coordinates
          of all the NPCs on the map and seeing who is in that cone and who is
          closest. This actually isn't that hard if you treat the map as a 2D map,
          however when you bring the z axis into the equations (maybe pc is looking
          up at a balcony), the computations get more difficult. Other than the
          mathematical complexity, the other issue with this approach is that
          python is slow compared to C++.
          A much easier method is using a console command to change something about
          the npc under the crosshair and then examine all NPCs for the change.
          Once found, change the "something" back.
          The two console methods I was able to use with this method:
              npc_hearing_sensitivity #.#
          I mention 2, because if you are trying to make a freeze gun, you don't
          want to depend on NPCs who are frozen to identify who is under the target
          hair. On the other hand, freeze doesn't take parameters, so it is ideal
          as you can accomplish the grapple without having to write to the
          console.cfg file. Here is an example:
            |Filename = [<vampire root>/Vampire/python/vamputils.py]             |
            | ...                                                                |
            | # STUN GUN...                                                      |
            | def OnUsedMyWeapon(targetNPC):                                     |
            |     print "TARGET [%s] " % targetNPC.GetName()                     |
            |     targetNPC.Faint()                                              |
            |                                                                    |
            | def OnPlayerAttackStart():                                         |
            |     if __main__.FindPlayer().HasWeaponEquipped("item_my_item")     |
            |         __main__.grapple=None                                      |
            |         __main__.ccmd.npc_freeze=""                                |
            |         __main__.ScheduleTask(0.1,'OnGrappleNPC()')                |
            |                                                                    |
            | def OnPlayerAttackEnd():                                           |
            |     pass                                                           |
            |                                                                    |
            | def OnGrappleNPC(found=0):                                         |
            |     if found:                                                      |
            |         OnUsedMyWeapon(__main__.grapple)                           |
            |     else:                                                          |
            |         npcs = __main__.FindEntitiesByClass("npc_V*")              |
            |         for npc in npcs:                                           |
            |             try:                                                   |
            |                 if (npc.playbackrate==0.00):                       |
            |                     __main__.grapple=npc                           |
            |                     __main__.ccmd.npc_freeze=""                    |
            |                     __main__.ScheduleTask(0.1,'OnGrappleNPC(1)')   |
            |                     break;                                         |
            |             except:                                                |
            |                 pass                                               |
            |                                                                    |
            | def FixAttackBinding():                                            |
            |     ...                                                            |
          Using npc_hearing_sensitivity is basically the same, however you have to
          use the console function (See III.3) to send the initial command.
              npc_hearing_sensitivity 1.2
          If an npc is found, you can use npc.TweakParam("HEARING 1") to
          fix without having to issue another console command.
    X. > > > > Miscellaneous
      A) Death
          When an NPC is killed, a copy of their instance name is placed in a
          global array called __main__.G.morgue[]. The IsDead() function ultimately
          looks up the name in the array to decide if someone is dead.
      B) Reserved Entity Names
          "!player" <- refers to the (potentially unnamed) player.
          "!playerController" <- refers to the (potentially unnamed) player
                                 controller if one exists. (There are used by cut
          "!dialogpartner" <- When you begin a conversation with someone, this
                              refers to the person you are talking to. It only
                              remains valid while the conversation is active.
      C) Special Embedded Entity Targets
          Some embedded entities have a model reference instead of a targetname.
          Model reference takes the form : *<number> ex: "*8".
          This represents the 8th instance of the class type at runtime. So if you
          ran FindEntitiesByClass() on the class of the embedded entity, *8 would
          correspond to the array[8] instance returned by the function.
          This means when you embed new data into map files, you should always
          append changes to the bottom so that you don't risk messing up other
          index references.
    XI. > > > > Legalities
      VTMB offers no provisional rights to mod developers. This has different
      implications in different regions, however the bottom line is this:
          YOU CAN'T MAKE ANY MONEY FROM YOUR MOD (ie : you can't sell it)
      This should not come as a surprise since free work is generally convention
      within the modding communities.
      Also, DO NOT distribute vampire.exe with your mod. Doing so is blatantly
      illegal and would be construed as distributing a pirated or "cracked" version
      of the game.
    XII. > > > > Common Scenarios and Examples
    A) Discovering a location on the map directly in front of or behind you:
    # USAGE : pc = FindPlayer()
    #         loc = TraceLine(pc.GetOrigin(),pc.GetAngles()[1],50)
    def TraceLine(pos, angle, dist):
        from math import pi as _pi
        from math import cos as _cos, sin as _sin
        # degToRad : r = d/(360/2pi)
        xoffset = dist * _cos((angle/(360/(2*_pi))))
        yoffset = dist * _sin((angle/(360/(2*_pi))))
        return (pos[0]+xoffset, pos[1]+yoffset, pos[2])
    B) Turn someone or something around 180 degrees. Calculates Facing.
    ## Usage : angle = pc.GetAngles()[1]
    ##         facing=(0,RevAngle(angle),0)
    ## Param 1 = angle degrees as a decimal between 180 and -180
    def RevAngle(angle):
        return (abs(((angle+180)/360)-0.5)*360)-180
    C) Figure out if 2 objects are within a certain distance of each other in 3D.
    ## USAGE :  npc = FindEntityByname("VV")
    ##          near = npc.Near(FindPlayer().GetOrigin())
    ##  Param 1 = location (x,y,z)
    ##  Param 2 = radius [default 200]
    from __main__ import Character
    def _Near(self,loc,r=200):
        # Avoid square root function. very inefficient
        # if (Distance)^2 > (x2-x1)^2 + (y2-y1)^2 + (z2-z1)^2
        return (r*r) > (xd*xd) + (yd*yd) + (zd*zd)
    D) Like Traceline, but you can offset the point by an angle. IE: 90 would be
       the point directly to your right. angle 0 would be the same as TraceLine().
    ## USAGE :  loc = FindPlayer().TraceCircle(50,90)
    ##  Param 1 = distance from entity
    ##  Param 2 = angle from entities current facing
    from __main__ import Character
    def _TraceCircle(self, radius=50, angleOffset=0):
        from math import pi as _pi
        from math import cos as _cos, sin as _sin
        pos   = self.GetOrigin()
        angle = self.GetAngles()[1] + angleOffset
        # degToRad : r = d/(360/2pi)
        xoffset = radius * _cos((angle/(360/(2*_pi))))
        yoffset = radius * _sin((angle/(360/(2*_pi))))
        return (pos[0]+xoffset, pos[1]+yoffset, pos[2])
    E) Test if the PC is in stealth or not:
    ## USAGE :  inStealth = FindPlayer().IsStealth()
    from __main__ import Character
    def _IsStealth(self):
        squating = ((self.GetCenter()[2] - self.GetOrigin()[2]) == 18)
        return (self.active_obfuscate or squating)
    F) Dynamically spawn an entity
    ## USAGE :  vv = SpawnEntity("MyVV")
    ## All but the first param is optional
    ## param 1 : entityName (string name of entity that you make it up)
    ## param 2 : entityType. VTMB internal classname. (def "npc_VVampire")
    ## param 3 : model. String specifying full internal model path.
    ## param 4 : distance in front of PC to create entity (def is 50)
    def SpawnEntity(entityName="", \
                    entityType="npc_VVampire", \
                    model="models/character/npc/unique/downtown/vv/vv.mdl", \
        pc = __main__.FindPlayer()
        position = pc.GetOrigin()
        angle = pc.GetAngles()[1]
        # calculate point in front of PC
        point = TraceLine(position,angle,distance)
        # reverse angle so npc is facing pc
        ent = __main__.CreateEntityNoSpawn(entityType, point, facing )
        try: ent.SetRelationship("player D_NU 0")
        except: pass
        try: ent.SetModel(model)
        except: pass
        try: ent.SetName(entityName)
        except: pass
        return ent
    G) Dynamically spawn an NPC
    ## USAGE :  vv = SpawnNPC("MyVV")
    ## All but the first param is optional
    ## param 1 : npcName (string name of NPC that you make it up)
    ## param 3 : model. String specifying full internal model path.
    ## param 4 : distance in front of PC to create entity (def is 50)
    def SpawnNPC(npcName="", \
                 model="models/character/npc/unique/downtown/vv/vv.mdl", \
        ent = SpawnEntity(npcName,"npc_VVampire", model, distance)
        return ent
    H) Dynamically spawn a physics Object
    ## USAGE :  stool = SpawnPhysics ("MyStool")
    ## All but the first param is optional
    ## param 1 : objectName (string name of object that you make it up)
    ## param 3 : model. String specifying full internal model path.
    ## param 4 : distance in front of PC to create entity (def is 50)
    def SpawnPhysics(propName="", \
                     model="models/scenery/structural/society/stool.mdl", \
                     distance=50 ):
        return SpawnEntity(propName,"prop_physics", model, distance)
    I) Teleporting and Moving NPCs
      1) Removing/Hiding
          All entities support the Kill() function, which removes the entity from
          the game world completely.
          Alternatively, you can set an Entity to hidden:
          And then Unhide it when you want to:
          Hide/Unhide result in physical entities completely disappearing.
          Other methods include setting the model to NULL
          Changing a model to null allows an entity to continue to fire events
          Without being seen.
      2) Moving and Teleporting Entities
          If you want your entity to WALK somewhere, most entites have a
          WalkToNode() method. The easiest way to move an entity is to use the
          SetOrigin() method
              npc = FindEntityByName("Ugly Dude")
                  < < < < < FREQUENTLY ASKED QUESTIONS > > > > >
      Q:  Why aren't there any Frequently asked questions?
      A:  Because this is the first release of the Guide.
                         < < < < < VTMB LINKS > > > > >
    1) http://www.vampirebloodlines.com/
      The official site of VTMB.
    2) http://www.planetvampire.com
      If you want to talk about the game, the forums here can't be beat.
    3) http://www.patches-scrolls.de/vampire_bloodlines.php
      Wesp's Unofficial Patch Website:
    4)  http://www.strategyinformer.com/pc/mods/..."
      Strategy Informers VTMB Page.
    5)  http://www.fileplanet.com/94454/0/section/Vampire:...
      FilePlanet's VTMB Page
    6)  http://browse.files.filefront.com/Vampire...
      FileFront's VTMB Page
    7) http://www.gamebanshee.com/vampirebloodlines/
      Game Banshee's VTMB Page
    8) http://www.tessmage.com/
      Tess specializes in Skin's and even supports his own Unofficial Patch.
    9) http://vh.noirscape.org/files.php?cat=2
      Vampire Heaven (Dedicated to Vampires). Includes some VTMB stuff:
    10) http://paine.planetvampire.gamespy.com/?action=files
      What can I say? It is Pain's website dediicated to VTMB. Doesn't look like
      it has been updated for almost 3 years, but it has a few unique downloads.
    11) http://vampirebloodlines.ru/combat/files/
       A russian fan site. You can translate it using google's translation service.
    12) http://corellon.clandlan.net/index.php?page=corellon/vtmb/index
      A spanish fan site. You can translate it using google's translation service.
    13) http://www.vampire-network.net/
      A french fan site. You can translate it using google's translation service.
                          < < < < < APPENDICES > > > > >
    A. > > > >  Entity Classes
      ai_script_conditions           logic_choreographed_scene
      aiscripted_schedule            logic_npc_condition
      aiscripted_sequence            logic_pythoncheck
      ambient_generic                logic_relay
      ambient_location               logic_squad_condition
      ambient_soundscheme            logic_timer
      camera_cinematic               logic_visibility_test
      camera_keyframe                math_counter
      camera_track                   move_rope
      env_beam                       mover_keyframe
      env_fade                       npc_VAndreiBlood
      env_floating_camera            npc_VAsianVampire
      env_particle                   npc_VBach
      env_particle_hud               npc_VBrujah
      env_physexplosion              npc_VCamera
      env_physimpact                 npc_VCameraSecurity
      env_shake                      npc_VChangBrosBlade
      env_shooter                    npc_VChangBrosClaw
      env_spark                      npc_VCop
      env_sprite                     npc_VDialogPedestrian
      env_steam                      npc_VGargoyle
      events_player                  npc_VGhoulCroucher
      events_world                   npc_VHengeyokai
      filter_activator_class         npc_VHuman
      filter_activator_feat          npc_VHumanCombatPatrol
      filter_activator_inventory     npc_VHumanCombatant
      filter_activator_mass          npc_VLasombra
      filter_activator_name          npc_VManBat
      filter_multi                   npc_VMingXiao
      func_areaportal                npc_VNewscaster
      func_areaportalwindow          npc_VPedestrian
      func_breakable                 npc_VProneDialog
      func_breakable_surf            npc_VRat
      func_brush                     npc_VSabbatGunman
      func_button                    npc_VSabbatLeader
      func_door                      npc_VScurrying
      func_door_rotating             npc_VSheriffMan
      func_dustmotes                 npc_VTaxiDriver
      func_elevator                  npc_VTzimisce
      func_illusionary               npc_VTzimisceHeadClaw
      func_keyframed_mover           npc_VTzimisceRunner
      func_lod                       npc_VVampire
      func_monitor                   npc_VVampireBoss
      func_movelinear                npc_VWerewolf
      func_particle                  npc_VYukie
      func_physbox                   npc_VZombie
      func_pushable                  npc_maker
      func_rotating                  npc_maker_fleshpile
      game_sign                      npc_maker_zombie
      game_text                      npc_payphone
      game_ui                        params_explosion
      hud_timer                      params_particle
      info_hint                      phys_animlink
      info_landmark                  phys_ballsocket
      info_node                      phys_constraint
      info_node_bach_run_1           phys_convert
      info_node_bach_run_2           phys_hinge
      info_node_bach_teleport_1      phys_thruster
      info_node_bach_teleport_2      point_camera
      info_node_bach_teleport_3      point_explosion
      info_node_bach_teleport_4      point_target
      info_node_chang_column         point_teleport
      info_node_chang_jumpbase       prop_button
      info_node_chang_ledge          prop_clockhand
      info_node_chang_teleport       prop_destructable
      info_node_climb                prop_doorknob
      info_node_cover_corner         prop_doorknob_electronic
      info_node_cover_low            prop_dynamic
      info_node_cover_med            prop_dynamic_ornament
      info_node_crosswalk            prop_hacking
      info_node_hint                 prop_haunted
      info_node_kick_over            prop_keypad
      info_node_link                 prop_largehull_ignore
      info_node_manbat_fly_to_point  prop_mover
      info_node_patrol_point         prop_padlock
      info_node_sabbat_arch          prop_physics
      info_node_sabbat_bottom        prop_physics_contested
      info_node_sabbat_dive          prop_radio
      info_node_sabbat_hide          prop_ragdoll
      info_node_sabbat_nojump        prop_sign
      info_node_sabbat_top           prop_slashable
      info_node_shoot_at             prop_switch
      info_node_tzimisce             scripted_sequence
      info_node_werewolf             security_camera
      info_node_werewolf_hint        sky_camera
      info_player_start              trigger_autosave
      info_target                    trigger_bomb_site
      info_teleport_destination      trigger_changelevel
      infodecal                      trigger_checkvolume
      inspection_brush               trigger_discipline_context
      inspection_node                trigger_electric_bugaloo
      intersting_place               trigger_environmental_audio
      intersting_place_conversation  trigger_hurt
      item_container                 trigger_impact
      item_container_animated        trigger_inventory_check
      item_container_lock            trigger_look
      keyframe_rope                  trigger_multiple
      light                          trigger_once
      light_dynamic                  trigger_player_activity_level
      light_environment              trigger_push
      light_spot                     trigger_small_hull
      logic_auto                     trigger_stealth_mod
      logic_case                     trigger_teleport
      logic_case_toggle              trigger_werewolf_zone
      Developer Notes:  How did I come up with this list?
      1) Used VPKTool to extract all maps (BSD) to txt files under meta directory.
      2) Installed CYGWin
      3) cd cygdrive/c/Program Files.../Vampire/maps/meta/
      4) cat `ls` | grep "classname" | sort | uniq > all.txt
    B. > > > >  Map Names
      1) Santa Monica                  4) Hollywood
           sm_pawnshop_1                    hw_609_1
           sm_apartment_1                   hw_ash_sewer_1
           sm_asylum_1                      hw_asphole_1
           sm_bailbonds_1                   hw_cemetery_1
           sm_basement_1                    hw_chinese_1
           sm_beachhouse_1                  hw_hub_1
           sm_diner_1                       hw_jewelry_1
           sm_embrace_1                     hw_luckystar_1
           sm_gallery_1                     hw_metalhead_1
           sm_gallery_1_particle_test       hw_netcafe_1
           sm_hub_1                         hw_redspot_1
           sm_hub_2                         hw_sewer_1
           sm_junkyard_1                    hw_sinbin_1
           sm_medical_1                     hw_tawni_1
           sm_oceanhouse_1                  hw_vesuvius_1
           sm_oceanhouse_2                  hw_warrens_1
           sm_pier_1                        hw_warrens_2
           sm_shreknet_1                    hw_warrens_4
           sm_tattoo                        hw_warrens_5
           sm_warehouse_1              5) Chinatown
      2) Los Angeles                        ch_cloud_1
           la_abandoned_building_1          ch_dragon_1
           la_bradbury_2                    ch_fulab_1
           la_bradbury_3                    ch_glaze_1
           la_chantry_1                     ch_lotus_1
           la_confession_1                  ch_ramen_1
           la_crackhouse_1                  ch_sewer_1
           la_dane_1                        ch_shrekhub
           la_empire_1                      ch_temple_1
           la_empire_2                      ch_temple_2
           la_empire_3                      ch_temple_3
           la_expipe_1                      ch_temple_4
           la_hospital_1                    ch_tsengs_1
           la_hub_1                         ch_zhaos_1
           la_malkavian_2              6) Special
           la_malkavian_3                   sp_boat
           la_malkavian_4                   sp_camwarehouse
           la_malkavian_5                   sp_epilogue
           la_museum_1                      sp_genesisdevice_1
           la_parkinggarage_1               sp_giovanni_1
           la_PlagueBearer_Sewer_1          sp_giovanni_2a
           la_sewer_1                       sp_giovanni_2b
           la_skyline_1                     sp_giovanni_3
           la_ventruetower_1                sp_giovanni_4
           la_ventrueTower_1b               sp_giovanni_5
           la_ventruetower_2                sp_lonewolf_1
           la_ventruetower_3                sp_masquerade_1
      3) E3                                 sp_observatory_1
           e3_chinese_1                     sp_observatory_2
           E3_Combat                        sp_smut
           E3_confession_1                  sp_soc_1
           E3_hub_1                         sp_soc_2
      Developer Notes:  How did I come up with this list?
      Answer) Vampire/vdata/system/mapnames_normalized.txt
      You can also see a list of most maps from console by
      Typing "maps". Not all of these maps are recognized
      (ie : nothing with sewer, smut, boat).
    C. > > > >  Item Name Summary
      item_a_body_armor                  item_k_hitman_ji_key
      item_a_hvy_cloth                   item_k_hitman_lu_key
      item_a_hvy_leather                 item_k_kiki_key
      item_a_lt_cloth                    item_k_leopold_int_key
      item_a_lt_leather                  item_k_lilly_key
      item_d_animalism                   item_k_lucky_star_murder_key
      item_d_dementation                 item_k_malcolm_office_key
      item_d_dominate                    item_k_malkavian_refrigerator_key
      item_d_holy_light                  item_k_murietta_key
      item_d_thaumaturgy                 item_k_museum_basement_key
      item_g_animaltrainingbook          item_k_museum_office_key
      item_g_astrolite                   item_k_museum_storage_key
      item_g_bach_journal                item_k_museum_storeroom_key
      item_g_badlucktalisman             item_k_netcafe_office_key
      item_g_bailbond_receipt            item_k_oceanhouse_basement_key
      item_g_bertrams_cd                 item_k_oceanhouse_sewer_key
      item_g_bloodpack                   item_k_oceanhouse_upstairs_key
      item_g_bluebloodpack               item_k_oh_front_key
      item_g_brotherhood_flyer           item_k_sarcophagus_key
      item_g_car_stereo                  item_k_shrekhub_four_key
      item_g_cash_box                    item_k_shrekhub_one_key
      item_g_chewinggum                  item_k_shrekhub_three_key
      item_g_computerbookhighgrade       item_k_skyline_haven_key
      item_g_computerbooklowgrade        item_k_tatoo_parlor_key
      item_g_driver_license_gamble       item_k_tawni_apartment_key
      item_g_drugs_drug_box              item_k_tutorial_chopshop_stairs_key
      item_g_drugs_morphine_bottle       item_m_money_clip
      item_g_drugs_perscription_bottle   item_m_money_envelope
      item_g_drugs_pill_bottle           item_m_wallet
      item_g_edane_print_report          item_p_gargoyle_talisman
      item_g_edane_report                item_p_occult_blood_buff
      item_g_eldervitaepack              item_p_occult_dexterity
      item_g_eyes                        item_p_occult_dodge
      item_g_gargoyle_book               item_p_occult_experience
      item_g_garys_cd                    item_p_occult_frenzy
      item_g_garys_film                  item_p_occult_hacking
      item_g_garys_photo                 item_p_occult_heal_rate
      item_g_garys_tape                  item_p_occult_lockpicking
      item_g_ghost_pendant               item_p_occult_obfuscate
      item_g_giovanni_invitation_maria   item_p_occult_passive_durations
      item_g_giovanni_invitation_victor  item_p_occult_presence
      item_g_guy_magazine                item_p_occult_regen
      item_g_hannahs_appt_book           item_p_occult_strength
      item_g_hatters_screenplay          item_p_occult_thaum_damage
      item_g_horrortape_1                item_p_research_hg_computers
      item_g_horrortape_2                item_p_research_hg_dodge
      item_g_idol_cat                    item_p_research_hg_firearms
      item_g_idol_crane                  item_p_research_hg_melee
      item_g_idol_dragon                 item_p_research_lg_computers
      item_g_idol_elephant               item_p_research_lg_dodge
      item_g_jumbles_flyer               item_p_research_lg_firearms
      item_g_junkyard_businesscard       item_p_research_lg_stealth
      item_g_keyring                     item_p_research_mg_brawl
      item_g_larry_briefcase             item_p_research_mg_finance
      item_g_lilly_diary                 item_p_research_mg_melee
      item_g_lilly_photo                 item_p_research_mg_security
      item_g_lilly_purse                 item_s_physicshand
      item_g_lillyonbeachphoto           item_w_avamp_blade
      item_g_linedpaper                  item_w_baseball_bat
      item_g_locket                      item_w_baton
      item_g_lockpick                    item_w_bush_hook
      item_g_mercurio_journal            item_w_chang_blade
      item_g_milligans_businesscard      item_w_chang_claw
      item_g_oh_diary                    item_w_chang_energy_ball
      item_g_pisha_book                  item_w_chang_ghost
      item_g_pisha_fetish                item_w_claws
      item_g_pulltoy                     item_w_claws_ghoul
      item_g_ring03                      item_w_claws_protean4
      item_g_ring_gold                   item_w_claws_protean5
      item_g_ring_serial_killer_1        item_w_colt_anaconda
      item_g_ring_serial_killer_2        item_w_crossbow
      item_g_ring_silver                 item_w_crossbow_flaming
      item_g_sewerbook_1                 item_w_deserteagle
      item_g_stake                       item_w_fireaxe
      item_g_vampyr_apocrypha            item_w_fists
      item_g_vv_photo                    item_w_flamethrower
      item_g_wallet                      item_w_gargoyle_fist
      item_g_warr_clipboard              item_w_glock_17c
      item_g_warr_ledger_1               item_w_grenade_frag
      item_g_warr_ledger_2               item_w_hengeyokai_fist
      item_g_warrens4_passkey            item_w_ithaca_m_37
      item_g_watch_fancy                 item_w_katana
      item_g_watch_normal                item_w_knife
      item_g_werewolf_bloodpack          item_w_mac_10
      item_g_wireless_camera_1           item_w_manbat_claw
      item_g_wireless_camera_2           item_w_mingxiao_melee
      item_g_wireless_camera_3           item_w_mingxiao_spit
      item_g_wireless_camera_4           item_w_mingxiao_tentacle
      item_i_written                     item_w_occultblade
      item_k_ash_cell_key                item_w_rem_m_700_bach
      item_k_carson_apartment_key        item_w_remington_m_700
      item_k_chinese_theatre_key         item_w_sabbatleader_attack
      item_k_clinic_cs_key               item_w_severed_arm
      item_k_clinic_maintenance_key      item_w_sheriff_sword
      item_k_clinic_stairs_key           item_w_sledgehammer
      item_k_edane_key                   item_w_steyr_aug
      item_k_empire_jezebel_key          item_w_supershotgun
      item_k_empire_mafia_key            item_w_thirtyeight
      item_k_fu_cell_key                 item_w_throwing_star
      item_k_fu_office_key               item_w_tire_iron
      item_k_gallery_noir_key            item_w_torch
      item_k_gimble_key                  item_w_tzimisce2_claw
      item_k_hannahs_safe_key            item_w_tzimisce2_head
      Developer Notes:  How did I come up with this list?
      Answer) Vampire/vdata/system/items/
    D. > > > >  Game States (Thanks to wesp for this list)
    -3 Tutorial.
    -2 Tutorial done, transition to haven.
    -1 Entered haven.
    0 Entered Santa Monica.
    1 Convinced Trip to sell you guns.
    2 Showing Elysium tip for the first time (temporary).
    3 Showing combat tip for the first time (temporary).
    5 Spoke with Beckett at warehouse.
    10 Entered downtown.
    15 Elizabeth Dane completed.
    20 Met Bach at Grout's mansion.
    25 Returned from Grout's mansion.
    30 Spoke with Beckett at Museum.
    35 Returned to prince from Museum.
    40 Spoke with Andrei (added by wesp).
    45 Spoke with Gary.
    50 Mandarin started experiments.
    55 Rescued Barabus.
    60 Spoke with Chang brothers (added by wesp).
    65 Returned to prince from Giovanni mansion.
    70 Spoke with Johansen.
    75 Returned to prince from Leopold Society.
    80 Spoke with Ming-Xiao after Hallowbrook.
    85 Spoke with Prince about Ming-Xiao.
    90 Spoke with Jack after Griffith park.
    95 Spoke with end-game cabbie.
    100 Cabbie takes you to Chinatown (Kuei-Jin ending).
    105 Not used.
    110 Cabbie takes you to Prince (Prince ending).
    115 Cabbie takes you to Anarchs (Anarch ending).
    120 Cabbie takes you to Chantry (Camarilla ending).
    125 Cabbie takes you to Chinatown (Solo ending).
    E. > > > >  Common Models
    F. > > > >  VCLAN Values (Patch 1.2)
    F.5.6 > > > >  VCLAN Values  (Patch 5.6)
    G. > > > >  Entity Details
    H. > > > >  Animations
    I. > > > >  Gestures
    J. > > > >  Console Variables and Commands
                    < < < < < Contributing Authors > > > > >
    Initial Guide Creation:
      -  Dheu
    General Advice:
      -  Wesp
                        < < < < < Final Words.... > > > > >
      The material presented in this Guide is the result of six months of
      trial and error with VTMB as I built my own mod. It includes the basics, the
      lessons that I learned, the bugs that I discovered and the workarounds for
      those limitations that I once thought would be show stoppers.
      One thing that I learned over the months is that there is SO MUCH that I
      still down known about this game. It is by no means complete and I invite
      others to share their knowledge with the community at large. Feel free to
      email me if you have a contribution to make to this Guide. If it is small, I
      can add it myself or if it is larger, I an give you temporary write/update
      access to the document.
      My ultimate hope is that this Guide will encourage other developers to create
      new adventures or add new game enhancements.