What do you need help on? Cancel X

Jump to:
Would you recommend this Guide? Yes No Hide
Send Skip Hide

Mod Developer Guide by rezzzman

Version: 1.0 | Updated: 10/03/2008
Highest Rated 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

    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.


      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


     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.


     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)}


      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


     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}{}{}{}{}{}{}{}{}{}


     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.


      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).


      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.


      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.

      [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


      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.

View in: