Last update: 2013-02-14
Welcome to the introduction to deCarnac's Bloodmap! I am deCarnac and the bloodmap is a tool I made for the online game Vampires! The Dark Alleyway.
First of all, this map is completely stand-alone and doesn't communicate with the game at all. This means the map cannot sense where you are in the game (it has no equivalent to a GPS), and what you do with the map will not affect anything in the game. It also means that the map doesn't mine the game for data or update itself automatically. It simply shows the data it holds, data which I have entered (and you may continue to add to). The map's Javascript code all runs locally within the browser, and it simply cannot "call home" or do other potentially fishy things.
You may use the map and read this document online, but you can also download it all from decarnac.atspace.eu. To be able to use the map you downloaded, make sure you get all the files and put them in the same directory (folder). The files are (total size approximately 0.21MB):
| Filename | Description | Really needed for offline use? |
|---|---|---|
| index.html | the map page | neccessary |
| vampireData.js | data used by the map | neccessary |
| ISODateFunctions.js | time code used by the map | neccessary |
| vampireDataText.txt | source database for the map | optional for basic use, neccessary for advanced use |
| favicon.ico | mouth with teeth icon | optional |
| readme.html | this document | recommended |
| screenshot.png | seen below | optional |
Open index.html in a web browser. It was developed on Firefox and Chrome, so those will work. Any standard-compliant browser should do fine. Even Internet Explorer promises SVG compliance in its latest version. You should see a page that resembles the screenshot below:
You can see the following five areas on the map:
Buildings can be seen on it only as tiny dots, as it gives you sort of a satellite's view. Try clicking the 16 parts of it. Notice how the District View changes, showing the part of the City you just clicked. The City View:
Buildings can be seen as squares here, as it gives you sort of a helicopter's view. At the left and top edges, you can see the street names. Notice how most buildings are black while some have another colour. Try hovering the mouse over a coloured building. You should see a tooltip describing the building. In fact, different types of buildings have different colours. Now try clicking somewhere in the District View. Notice how the Zoom View changes, showing the part of the City you just clicked. Try this at or near a coloured building, and you should see it in the Zoom View too. The District View:
This is almost resembling the game view, but here you can see in a three-square radius. You can see the street names at the crossings, and any coloured buildings in view have their descriptions written on them. Now try clicking somewhere in the Zoom View. The Zoom View changes, and centers on the square you just clicked. This lets you pan the Zoom View a bit from within it, perhaps to center on a building or to get more in view. The Zoom View:
You can look up and locate any named building or address. Locate the blue button that has a magnifying glass, it is in the Button Menu. Click it. The button gets a bright white border and the Search panel appears. You can move the panel around on the screen in a drag-and-drop fashion. This is done by pressing the mouse button over the panel's green title bar, moving it with the mouse and then releasing the mouse button.
Click the Shops button to list all known Shops. You can also click the Guilds button to list all known Guilds. The search fields will be ignored when using these buttons.
Note that if no recent data about shops or guilds has been imported, no such buildings will be found. Data import is described in a later chapter.
Enter a part of the name (at least one letter) of the building you are looking for in the Name field, and click Search. If anything on the map matches the search, it should then appear in a list. The list shows type of building and a Zoom button. Clicking the buttons will make the map views zoom in on that building. Any street name matches also appear, but entire streets cannot be zoomed to.
If you search for a short, common sequence of letters (just an "e", for example), the list of matches will become very long. Either refine your search or be prepared to scroll down to find what you are looking for. All matches are sorted in alphabetical order.
You can also search for a specific street address. Enter one or more letters in the street's name in the Name field, just like you would when searching for a building. In addition, enter the Street number in the (Number) field and click Search. Any matches should appear as crossings, each with a Zoom button.
You can make the Search panel disappear again either by clicking the activated blue button a second time, or by clicking the panel's close button marked X.
Waypoints let you plan your travelling. Select your current location and the intended destination, and the map does the rest (apart from the actual travelling). They also let you choose the optimal transit stations and whether to use transit at all. Last but not least, the distance to the bank closest to your current location is displayed. The waypoint controls are all found in the Button Menu.
Click the red button marked Set ⊙. Notice how the button gets a bright white border, showing it's active. Now hover the mouse over the District View. A grey ring will follow. Try hovering over the Zoom View as well, and you see a grey ring there too. Click somewhere and the grey ring will become a bright green ⊙ marking your selected location. The symbol will be visible on all three map views.
Click Set ⊙ again. You can abort changing location by clicking the activated button again. The bright white border an the grey ring both disappear to show this. The previously set location remains where it is.
Click the red button marked Set ⊗ to set your destination. You do this exactly like you would set location as described above. Try setting a destination more or less far from the location, and see what happens.
Click the green button marked Zoom ⊙. The Zoom View will immediately center on the location marker. In addition the District View will change to where the location is. You can explore the map freely by changing the three views, and when you are done return to your location with just another click at Zoom ⊙. You can also show your selected destination in exactly the same way by clicking Zoom ⊗. You may try zooming back and forth beween location and destination.
Locate the three purple buttons in the Button Menu. Each of them has a symbol and displays a number. The number represents a distance, measured in minimum number of Action Points (AP) needed to cross it. Hover over the buttons and read the tooltips. The buttons show:
The transit distance may not show a number, but instead a dash (-). This means that using transit is no better than walking, which is normal for short distances. The transit distance takes the 3 AP needed to go by transit into account.
Click the Bank distance button, and it becomes active. All three map views will now display a green polygon (or possibly a diagonal line) from your location marker to the bank closest to it. The green polygon represents the possible paths you may move along while still reaching the bank using the minimum amount of AP. You may hide the path by clicking the button again, or leave it showing. The path will be updated whenever you change the location marker. If two banks happen to be equally near, the map just picks one of them.
Click the Walking distance button, and it becomes active. If another path was active, it will be turned off in favour of the one you just activated. The walking path works like the bank path, but from your location to the destination. It will be updated whenever you change the location marker or the destination marker.
If no number is showing in the Transit distance button, try selecting a destination far from your location. Then click the Transit distance button and it becomes active. The transit path works like the walking path, but it takes transit opportunities into account. You will now see two green polygons on the map views. The first is from the location to the closest transit station, the second is from another transit station to the final destination. They will be updated whenever you change the location marker or the destination marker. In addition, the two station names appear vertically below the button. This becomes useful when standing at the station in-game and selecting where to go. The one you are at will not be available to go to, so simply pick the other.
At the top of the button menu are two circles that aren't buttons. They are countdown clocks that display the time before the in-game shops and guilds are predicted to move again. Hover the mouse over them for more detailed information. The small circle is the shop clock, and a full circle represents their move interval of 12 hours. The big circle is the guild clock, and each of the ticks along its edge represents 24 hours (guild move intervals are 3-5 days).
The clocks should work regardless of your timezone. They also try to take the game server's timezone effects into account. However, the displayed times are derived from historical observation, and reality have changed in the past and most likely will again. Don't treat the displayed times as absolute truth. The move clock settings of the map can be changed if you get better information (see Advanced Use).
You now master all the basic functions of Vampire deCarnac's Map of RavenBlack City!
The shops and guilds in the game change locations at certain intervals. Their future addresses are either random or follows a pattern known only to the game designer, Raven Black. Our only data comes from players who find these buildings, either via pub tips or stumbling upon them, and then share the infomation. The best website I have found for this is aviewinthedark.net (AVitD) by cliffburton. It is a very clever automated database, where you, I and other players can report our findings and get neat tables of everything found since the last relocations.
This chapter will show you how to most easily get that information into the map. This data will only last for that session, meaning they will be gone from the map the next time you open it (or if you refresh). Since shop locations are never good for more than 12 hours anyway, this map amnesia between sessions is less of a problem.
Below the map are two buttons. Click the one that says to show the import dialogue. You should now see a box appear below the map. It contains some buttons, a brief instructive text, and a large text field. You may need to scroll down the page a bit.
First, there is a button named . Clicking it will simply hide the import dialogue. You can try it, and then re-open the dialogue by clicking again.
Below are some step by step instructions. Try them out. Clicking the AVitD link should open that webpage in a new window. When at that page, mark all text (by pressing Ctrl+A). Then copy the marked text (by pressing Ctrl+C).
Go back to the map page. Click anywhere in the large empty text field, and a text prompt should appear. Paste the copied text (by pressing Ctrl+V). Lots of text should appear in the field, among it the names and addresses of shops and guilds. Complete the process by clicking , which will also close the import dialogue.
The map will then parse the text input looking for names and addresses of shops and guilds. Any such found will immediately appear on the map. The existence of shops and guilds on the map will make their respective clocks display in colour (blue/green instead of grey). You can spot the new buildings on the map views, or easily search for or list them via the Search panel.
Any new shop locations will replace all previous shop locations, so import them all at a time. The same applies for guild locations, although you usually import them both together. If the script cannot find any shop or guild names in the input, nothing will happen.
Since the points in time when the shop and guild moves occur in-game are estimated, these are potential sources of error. If the time script at AVitD is say one hour early, old locations may accidentally be re-reported there and show up for most of the following period even though they are obselete. The time settings in the map itself form another source of error, if they are too far from what is the current reality in-game. Then there is always the possibility that false data has been posted at AVitD, be it by accident or malice.
Bottom line is to consider these things carefully, and not to automatically consider imported locations as 100 % accurate. As the old computer proverb goes: Garbage In, Garbage Out.
You now know how to get shops and guilds to show up in Vampire deCarnac's Map of RavenBlack City!
The following instructions involve changing persistent map data. This requires that you have downloaded all relevant map files (see the beginning of this document).
The text file VampireDataText.txt holds essentially all the data that is displayed on the map. Lets have a look at it. Open it in your favorite text editor. This may be Notepad, MS Word or OOo Writer, but personally I prefer Notepad++ (it's free). If you are worried you'll break something, just make a backup copy of the file before editing. Then you can go wild.
The file has well over 500 rows of content, but it basically consists of tables and comments.
There are sixteen tables, which all begin and end with certain tags. These tags begin with a # and are in CAPS. The first table is a bit special. It begins with #SETTINGS_START and ends with #SETTINGS_END, and contains clock settings which will be described in detail below. All the other tables begin with #TABLE_START and end with #TABLE_END. Note that the #TABLE_START tags are directly followed by three values on the same row. More about those later.
Everything between the start and end tags is data. Everything outside the tables is commentary text, meaning it is there for you as a human reader only (the script will ignore it at conversion). Comments may include anything except table tags. Feel free to add your own!
As you may already have read from the comments, the data on every row is tab-separated. That means it is very important that the data columns on each row is separated by a single TAB. The script will look for tabs as separators, so substituting them with a number of blank spaces will not do. More than one tab will also cause problems, as it is treated as another column.
Rows are separated by a single return (enter) as you might expect. Blank rows within a table are not allowed. Tables are allowed to be empty, and some of them are. When that is the case, the table starting lines hold all their important info.
Each table's start label are followed by three values (tab-separated). An example:
| #TABLE_START | lair | Lair | #660033 |
The columns are, in order:
What can we do with this? Well, if you dislike the term Lair, you can replace it with, say, Mansion. If you don't like the maroon colour they have on the map, you can replace #660033 with, say, #FF0099 (pink). All such buildings will then display as pink Mansions on the map after the data conversion is done (see below). There is no end to the possibilities.
There are three tables (apart from the Settings table) that do not contain building locations and lack a color code in their starting line. These are street, guildpowers and shopgoods. Here is a description of them and what they do.
This contains the entire list of street names in RavenBlack City, both east-to-west and north-to-south, togther with a coordinate. These are very unlikely to change in-game. The script uses this table frequently to look up addresses and convert them to coordinates (and vice versa). Avoid messing with it.
These list the known guilds and shops respectively, and hold an informative text about what each of them offer. The tables are used in two ways. First, they are used by the script at data import to detect valid names of guilds and shops and determine what they are. Secondly, the tables are used to provide tooltips for those buildings when displayed on the map. An example:
| Allurists Guild 1 | Charisma 1 (1000 + Q), Perception (7500 + Q) |
The table content has two columns: name and tooltip text. The tooltip text in these tables get special treatment. Each , (comma) in them will result in a line break in the resulting tooltip. This allows neater tooltips for shops and guilds.
In the unlikely event that a guild or shop changes name or new (moving) ones are introduced in the future, you will have to add them here. You are free to edit the tooltip text. You you want to include all items sold in each shop in their tooltips, go ahead!
Lets look at what is inside the building tables. To recap, it is the tables that has a color code in their starting line and addresses in the content. From the comments you can get a description of how each table is organized. Some tables have their own content format, but all those that contain building locations look something like this:
| Devil Miyu's Lair | SE of Fear and 1st | 2012-03-26 |
The columns are, in order:
What can we do here? Let's say you have found a lair that isn't on the map. Locate the lair table, and you'll see that it is written in alphabetical order. This is just for convenience, and the map script doesn't care. See if the lair isn't already in (at another address). In that case it has moved, and you just have change the address. Otherwise, insert a new row and either copy-paste or type in the name of the new lair followed by TAB, then SE of and the address. Add a comment if you like.
As for the other buildings, some are unlikely to change. The banks and stations have to my knowledge never changed. Several of the pubs have changed names, but they remain where they are. Other buildings have appeared quite recently. The Special Shops are not that old, nor is the Battle Arena. These formed new building types, and required tables of their own. What if another brand new type of buildings are introduced? Just add a new table!
Let's say Raven Black introduces the new building type Discotheque, with cyan in-game signs. You can then just add the following somewhere at the end of the text file, assuming these are the known buildings of this new type:
| #TABLE_START | disco | Discotheque | #00FFFF |
| Studio 54 | SE of Horror and 54th | ||
| Tech Noir | SE of Killjoy and 66th | ||
| #TABLE_END | |||
When you later convert the text file, the script will recognize this as a building data table and include it as just another building type. As easy as that. Just make sure the table tags and all data rows are in order. The table identifier (in this example disco) should consist of letters a-z and must not be used by another table.
The settings are found early in VampireDataText.txt together with comments about what they are. As you can see, they are all about time. They control the shop clock and guild clock, and how the movement schedule of those locations is predicted. This is how they look:
| #SETTINGS_START | |
| guildMoveDays | 1,6,10,14,19,23,27 |
| guildMoveHours | -1 |
| guildMoveMinutes | 0 |
| shopMoveHours | 9 |
| shopMoveMinutes | 45 |
| serverSummerTimeProtocol | US |
| #SETTINGS_END |
The value next to guildMoveDays is a comma-separated list of dates. Guilds are assumed to move at, or immediately before or after, those dates each month. This date pattern has been stable in-game since the guilds were introduced. However, the actual moment the guilds move is occasionally shifted by several hours. This may even make end up in the preceeding or following day.
An online game like Vampires! is played across the globe. I myself am in a timezone seven hours ahead of the game server. For this reason, the time numbers in the map settings are given according to Coordinated Universal Time (UTC) which is practically the same as Greenwich Mean Time (GMT).
Some particular rules apply. In the case of guild hours, numbers higher than 23 or even negative numbers are allowed to adjust it relative to the list of days. In the particular case of shop hours, it is assumed they always move every 12 hours. This means 9 has the same effect as 21.
The serverSummerTimeProtocol setting is the most experimental, and I haven't been able to confirm if it is needed at all. The game server is located in Houston, Texas, USA. Either the shop and guild movement times are linked to its local time, or standard time. If it runs on local time, it will shift relative to UTC during summer, when Daylight saving time (DST) is applied in North America. Otherwise it will run in parallel with UTC. If you believe the server runs on local time, use the value US. If you believe it runs on standard time the entire year, use the value none. To be certain which it really is, you will have to monitor in-game shop disapperances right before and after North America shift from or to DST, and see if if there is a difference. Or you can ask Raven Black, but I suspect he wants to keep this information to himself (otherwise it would be in the game FAQ).
In-game observation is the only source of accurate time values. Here is how it can be done:
You can apply the same method on guilds, but then you have to wait inside it since guilds aren't visible from the outside.
Unfortuneately, just updating VampireDataText.txt will not change the map. The map is run through Javascript, and it cannot access text files unless you order it to. Javascript can however easily access .js files, so the contents of VampireDataText.txt is to be converted to new data for vampireData.js. As you already know, the file vampireData.js holds all the data the map script uses.
Now you may ask: Why bother with the text file? Why not edit the .js file directly? These are good questions, so lets open the two files in your text editor and compare them. As you will see, the .js file is more thoroughly formatted using quotation marks, commas, brackets et cetera. This is neccessary in order for the script to understand it. A single misplaced quotation mark here will practically always make the script stop and the map will not show up at all. That is an error that is easy to make but hard to find! In addition, the .js file stores locations as coordinate numbers rather than addresses. This is efficient for the script but obscure for us as human readers. For these reasons, the text file is there as a more human-friendly source, while the .js file is more of machine-code.
The map file itself has the conversion tool, so open the map. Below the map to the right you see the button . Click it to open the conversion dialogue. You should now see a box appear below the map. It contains some buttons, some brief step-by-step instructions, and a file browser field. You may need to scroll down the page a bit.
First, there is a button named . Clicking it will simply hide the dialogue, just as the Cancel button in the import dialogue does.
Let's try importing the text file you edited. Click the file browser field or button, and a file browser window should appear. Navigate to wherever your edited version of VampireDataText.txt is, select it and click open. Note that this is your web browser looking into your system, and it cannot do anything to it other than attempt to read the file you select. VampireDataText.txt will not be affected, nor will anything else. Click to start the conversion.
The script will immediately parse the text file you opened, and convert its data to .js format. A new window opens, and you may recognize its contents. This is the text for a new vampireData.js based on the data you provided.
The next step is to store it. As I mentioned earlier, Javascript cannot mess with your files. This means the script cannot save data by itself, so you will have to do it using your text edtor. Since the formatting is already done, it's mostly a formality.
Mark all text of the new window (by pressing Ctrl+A) and copy it (by pressing Ctrl+C). You can then close that window. Open vampireData.js in your text editor if you haven't done it already. Select all its text (by pressing Ctrl+A) and replace it with the new (by pressing Ctrl+V). Save vampireData.js. The conversion is complete. Reload the map to see the results of your editing. Any buildings you added should appear!
You now master every usage aspect of Vampire deCarnac's Map of RavenBlack City!
The next logical step is for you to dive into the map code itself, but that is beyond the scope of this introduction. Good luck and have fun!
Sincerely,
deCarnac