|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
CONTENTS |
Index | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Index |
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. Requirements: 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. 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. c:/myproject/myapp.dbpro 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: walls/brick_01.jpg 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. FAQ 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. c:/game/map.csm c:/game/tiles/tile1.bmp c:/game/tiles/tile2.bmp DO NOT copy the texture files alone otherwise your map file will fail to load.
|
