Independent Software Solutions 



Online Tools





Cartography Shop - DarkBASIC Professional map importer plugin v3.2.x

Welcome to the Cartography Shop map importer plugin for DarkBASIC Professional which allows you to load Cartography Shop v4.x maps directly into DarkBASIC Professional using a single command.  This new release has two new functions which will make life a lot easier to manipulate pivot based mesh groups by using the new CSM GROUP TO PIVOT function.

Effectively, this new function should be used together with CSM OBJECT TO GROUP which returns a group ID based on an object ID retrieved from a collision event such as the Nuclear Glory collision library or DarkBASIC Professional's internal collision system. 

Improvements over previous versions will be evident the second you start using the tool.  SPEED!  On average, previous versions took several seconds to a minute when loading complex map structures, and it was also difficult to remember all the function names and their use.  All functions have been fully documented here.


This version of the plugin requires DarkBASIC Professional v1.5.5 and above.  Please ensure that you have upgraded your version as I will not support any technical issues with this plugin if you're version is not up to date. 

Changes from v3.1.6/7 to v3.2.0

The importer has now been updated with two new functions:


A proper installation system has now been created to make installation easier.

Changes from v3.1.4 to v3.1.5

People have asked for the ability to include map files and textures as included media files for DarkBASIC Professional applications.  This is now possible.  But, it does take a little time on your part to ensure that you include EVERY texture image that the map requires, and there are rules for this.

First, you must include your .CSM map file(s) into the Media list for your project.  This doesn't require any specific rule, it could be located in a subfolder off your main project directory, but as long as the path you specify is the same for LOAD CSM, this should be ok.

IMPORTANT:  When you include your textures, this has to be done correctly otherwise you will have problems when loading your map.  Because textures for a map are stored in category folders like Cartography Shop manages, i.e. walls/brick_01.jpg, this is exactly how image files must be included in your media list.  Now this is pretty straightforward.  All you need to do is make sure that your Category folders are subfolders off your main project, i.e.


Now when you include the textures into your media list, the editor should store them relative to the main project, so you should see in your media list, the following files:


Abide by these rules, you should then be able to store, compress and encrypt all your maps and textures as part of your application.  You must also place a new command into your application code - CSM INCLUDED AS MEDIA.  Specifying 1 as the parameter.  This instructs the importer plugin to treat the paths as included media, and it also removes file existance checking from the texture loader.  If your code still requires loading map files from disk ASWELL, you must call the above function with parameter 0.

Changes from v3.1.1 to v3.1.3

The two functions CSM SET MAP and CSM GET MAP have changed in the way in which maps are identified.  In v3.1.1 and before, the map number was identified by it's position in the map list, i.e. if you had three maps loaded, you would select each map using values 0, 1 and 2.  This is fine, but what happens if you deleted map number 1.  If you identified maps with this method in DarkBASIC Professional using a variable list, you would need to update your variables for all maps after the map you deleted because map 2 would become map 1.  This posed a problem, so this has now changed.  Any new map that is loaded will be assigned a unique identifier starting from 0, which is incremented for every map.  You would obtain the ID of the last loaded map by calling CSM GET MAP.  So if you loaded three maps, they would be assigned ID values 0, 1 and 2.  Deleting map 1 would still yield maps 0 and 2.  I hope this is better for you.

Major changes in functionality from v3.0.x to v3.1.x

The importer v3.1.0 has been modified significantly from previous versions.  In previous versions, all meshes and their faces were represented in DarkBASIC Professional as individual objects.  This posed a problem for people using collision detection in that the collision system had to be registered with all objects involved with the collision event.  This is no longer the case.

A DarkBASIC Professional object is now created for each top most GROUP in your map.  If your map does not contain any groups, your map will be represented as a single DarkBASIC Professional object.  The philosophy behind this scheme is that when you build your maps, it is good design ethics to break down your map into groups of meshes for each section.  For example, if you have a map that consists of two rooms with a door separating the rooms, the two rooms could be classed as a group of meshes.  The door itself would be classified as a single group which contains one or more pivot entities.  The example that comes with this update of the importer, demonstrates how the door can be opened and closed using the pivot entity assigned to the door group.  It also demonstrates the use of child pivot entities.

All groups that contain pivot entities can be moved and rotated in anyway you see fit.  Also note that child groups are affected by the manipulation of their parent groups.  If you run the example, you can see that although the door is swinging back and fourth, the hatch is also swinging relative to the door position.

You can now show and hide the currently selected map.  This is ideal for visibility checking against a map's entity position with your camera so that you can show and hide multiple maps for a simplified portal viewing system.  If your maps are designed to be small, you could create extremely large map areas using multiple collections of maps, and test against each map's visibility entity (you must define this yourself) with the camera position.  If the camera position is too far away from the entity, just hide that map!!!

Maps can now be loaded directly from a DarkBASIC Professional memblock.  Ideal for encrypted memblock(s) from files to protect your map data.

You can now set the initial image identifier for all textures that are loaded when you load your maps.  Use CSM INITIAL IMAGE.

Finally, when you clear a map using CSM CLEAR, all objects are now deleted for that map.  A change was made in an earlier version which caused replacement of existing objects in memory when a map was loaded.  This no longer occurs.  Therefore it is recommended that you decide upon an object starting number with CSM INITIAL OBJECT before you call LOAD CSM or MAKE CSM FROM MEMBLOCK.

Because of these changes, please review function descriptions to ensure that you familiarise yourself with the new scheme because some of the function may not operate in the same way as previous versions of the importer, and some of the functions are now obsolete.

Using the plugin 

ENSURE that you add the csmplugin.dba as an include file to any project you develop that uses the plugin.  This is required to ensure that all DarkBASIC language components are compiled into your application that are also used by the plugin.  If you fail to include this file, you will experience problems trying to load your Cartography Shop map files.

Error handling 

In v3.0.6, a new change has been made to the way error handling is dealt with when using the plugin functions.  Two new functions are now available from DarkBASIC Professional:


The plugin now uses an error state which is set when ever an error occurs from within the plugin.  Originally, if an error occurred, a message box was issued by the plugin, but this caused problems for some people.  Every time you call any of the plugin functions, the error state is cleared, but once an error occurs, CSM ERROR will return a non-zero value depending on the type of error.

CSM ERROR TEXT will return the textual description of the error that last occurred.  You can now use these two functions to check whether an error occurred during the execution of your program without message boxes appearing.


Q.    I'm confused about IDs or indexes and Media Identifiers etc?

A.    Most of the functions available in the plugin use IDs or (indexes) to reference the actual data in your map file.  There is a difference between these indexes and the standard media identifiers for commands used by DarkBASIC Professional.  To clarify this, if you use the DarkBASIC command LOAD OBJECT, or MAKE OBJECT for example, these functions require a (Media Identifier).  The plugin functions require a different type of ID, or more commonly referenced as an Index.  All functions that require an Index must begin from 0 and increment depending on the total number of available references in the map file. 

Q.    How do I obtain the position of a mesh in my CSM file?

A.    There are two ways.  Either obtain the object media identifiers of surfaces associated with a mesh and use the DarkBASIC Professional OBJECT POSITION X/Y/Z functions.  A more flexible method would be to assign a pivot entity to a group of meshes and use the entity's position instead.  The latter method is more appropriate because if you use the pivot move or position functions, the entity position will also be updated.

Q.    How do I remove an existing map from memory and load a new one quickly?

A.    Ensure that you have disassociated any references to meshes, groups and entities in your program and just call CSM CLEAR.  The current map will be cleared from memory, including texture images.  Now use the LOAD CSM command to load the new map into memory.

Q.    How do I animate my map textures?

A.    The plugin does not support animated textures directly, but you can use the CSM TEXTURE CREATE and CSM TEXTURE MESH  to replace an existing mesh texture image with a new one.  Using these functions with DarkBASIC Professional images, you can effectively create animated textures on meshes etc.

Q.    How do I setup collision for my map?

A.    Please see the collision documentation section for further details on this matter.  ( This is an ongoing plugin development )

Trouble shooting

Some users may experience problems loading map files if they have not placed their map textures in the correct location.  The importer requires that all your textures are copied from the Cartography Shop /Textures folder, including the category folder that they belong into the same location as your map file.

So, if your Cartography Shop textures folder contains a category such as 'Brick' or 'Tiles', you must copy this category folder to the location of your map, i.e.




DO NOT copy the texture files alone otherwise your map file will fail to load.





v3.2.4 Fixes on previous minor versions were to ensure proper texture display as there were problems related to ongoing changes in the DarkBASIC Professional source base.
v3.2.0 New release to work with DarkBASIC Professional v5.8 
v3.1.6 Fixed a bug that seemed to screw up property strings for entities, groups and meshes.  Also added a new CSM FLAGS function.
v3.1.5 Modified the plugin to now work correctly when including maps and textures as added media files.
v3.1.4 Fixed a couple of minor bugs, and CSM GROUP TO OBJECT should now work correctly.
v3.1.3 Modified the behaviour of CSM SET MAP & CSM GET MAP.
v3.1.2 Fixed a bug which causes certain machines to fail when using the plugin.  This should not happen now.
v3.1.1 Added several new functions and also sorted out a MAJOR problem with group indexing.
v3.1.0 Major changes to this version, please see the beginning of this page for details on the changes.
v3.0.12 Fixed two problems that were found by one of the plugin users.  Reversed textures, which I cannot believe I missed!!  And also resolved an alpha texture problem.
v3.0.11 Fixed a bug that prevented maps from being loaded if absolute paths for maps were specified.  Also improved on the function documentation and corrected a few misunderstandings, well, I'm only human ;)
v3.0.10 Now supports full multimap loading.  Basically you can load two or more maps simultaneously and access each of their entity and mesh properties without any change to your code, just use an additional CSM SET MAP command.
v3.0.9 A slight misunderstanding on how the offset command should work for certain users, now fixed.
v3.0.8 Fixed transparency, got fubar'd during the change to single mesh rendering.  Also added a new function to allow map offsetting before loading any map.
v3.0.7 Vast improvement, all maps can now be loaded using a single mesh with full lightmapping.  Also able to control the blend mode using CSM BLEND MODE.
v3.0.6 Beta Modified the error handling system, requests from users
v3.0.5 Beta Added mesh collision usage function and also fixed releasing of textures and lightmaps when map is cleared
v3.0.4 Beta Added pivot functions and various mesh/texture handling functions
v3.0.3 Beta Fixed a memory leak problem
v3.0.2 Beta Added new query functions and fixed a bug with the multitexturing flag when loading a map.
v3.0.1 Beta Added lightmapping support
v3.0.0 Beta Initial beta release - This release is a beta test for the plugin.  It doesn't support any of the available features in previous versions of my CSM importer code, originally written in DarkBASIC Professional.

With this version, you can load CSM map files, but this is a general test for compatability issues and speed improvements.


(C) Paul S. J. Millard 2006