__________ .___ .___ \____ / ____ __| _/ __| _/ / /_/ __ \ / __ | / __ | / /_\ ___/ / /_/ |/ /_/ | /_______ \\___ >\____ |\____ | \/ \/ \/ \/ Zedd Collision Library Alex Marcolina Omnimaga.org Builderboy2005@yahoo.com Table Of Contents: ---------------------------- I Description II Features III Installation IV Advanced Installation V Data Storage VI External Libraries VII Callback Features VIII World Collision IX Important Notes ----------------------------- ****************************************************************************************************** I Description ****************************************************************************************************** The Zedd Collision Library is a physics engine designed to be used in Axe games that need advanced physics, with a high level of customization and ease of use. The Zedd engine handles all of the objects in your world, while simultaneously solving for the collisions between the object and its environment, as well as object-object interaction. Zedd is built with the purpose of being used in games, which is why it comes with the ability to be linked with external libraries. This allows extra physics effects to be added on top of the Zedd collision solver independently without any compatibility issues. Now with Zedd, your games can feature realistic physics across all objects, and advanced effects such as ropes, springs, moving platforms, and much much more ****************************************************************************************************** II Features ****************************************************************************************************** Zedd is primarily a collision solver, handling the interactions of objects and when they collide with the world around them. Though simple, Zedd has a plethora of features that can be customized and expanded to make Zedd be the perfect engine for your game: PHYSICS FEATURES: -Tilemap Collision All objects collide with the tilemap you provide, with setable parameters for map width and tile size. -Object Collision All objects also collide with all other objects in the simulation, preventing objects from getting stuck inside each other -Elasticity Basic elasticity is supported on object-world collisions, as well as object-object collisions This controls the 'bounciness' of the objects when they collide, and can be customized -Friction Friction is supported on object-world collisions, as well as object-object collisions Each object holds its own coefficient of friction, which can be changed to allow some objects to slide around like ice, while other objects tend to stick like rubber -Mass Each object has its own mass property, which is affects forces and collision response -Momentum Momentum is conserved in all collisions, which takes into account masses and velocities of objects. Smaller objects will have a harder time moving objects with more mass, and visa versa. -Axis Locking Zedd allows objects to be locked on a specific axis, which prevents movement in that direction. This allows moving platforms to stay floating in the air, yet still move back and forth, as well as supporting objects that do not move at all, but are still customizable. Zedd also ensures that you will never have to mess with the actual Zedd code in order to get your game to work. Zedd is entirely controllable through subroutines and libraries, which make achieving excellent physics in your game easy! INTERFACE FEATURES: -Force Based Library Support Zedd is a force based system, which allows external libraries to interface directly with Zedd and introduce extra effects and types of forces that will automatically work alongside the Zedd solver -Callback Function Zedd has a powerful callback function feature whereby the user can define a function that Zedd automatically applies to each object during each frame of the simulation. This allows global forces to easily be applied to the world -Intuitive functions Zedd includes many intuitive functions such as location and velocity setters, as well as functions to add, remove, or modify objects that are in the world. Zedd can be completely initialized and handled through the sole use of subroutines ****************************************************************************************************** III Instalation ****************************************************************************************************** Zedd has multiple methods of installation, as well as ways to customize your engine for your games specific needs. We will be going over both methods of installation here. SIMPLE INSTALATION In the main directory, there are 3 Program files. Each of these is a different version of the Zedd Engine: -Zedd1 The fastest of the three engines, using only minimal resources, and holding a minimum of features, this version is for those who need extreme speed in their games -Zedd2 This version is a balanced engine that has a good amount of features to be usable in any game, but is slightly slower than the first engine. This engine is a good all-around engine that can be used in any game -Zedd3 This is the version with the maximum amount of features, but is consequently the slowest. This is the version to use if you have a game that does not need too many objects, and an emphasis on highly accurate physics. Also an option if your game is going to be 84+ only, and you are going to rely on 15Mhz To install Zedd, first send the program to your calculator, and then modify your program to reflect this template: :.My Program //Start of your program :L1->GDB0OB //Define area where Zedd will store its data and objects :L4->GDB0VR //Define the location that Zedd can use for its temp variables :4->GDB0FR //Define the default frictional constant :LoadZ(0,15) //Loads a Zedd simulation with gravity 0 in the X direction and 15 in the Y direction : :NORMAL GAME CODE //Whatever your game is : :Return //Exit Game : :prgmZEDD1 //ZEDD Subprogram code :LBL CallZ //Mandatory Callback Function :Return //Return Callback Function ****************************************************************************************************** IV Advanced Installation ****************************************************************************************************** Although the 3 basic Zedd programs that are offered in the main directory are usually going to be sufficient for many physics games, Zedd also gives an option to build a custom Zedd engine from individually customizable modules. In order to keep speed at a maximum, the way customization is handled is through including different versions of the same module to your calculator. For example, if you wanted the advanced Friction module, you would send FRICTION LEV3 to your calculator. All friction programs have different names on the computer, but all appear as the same name (ZFRICTN in this case). More instructions, as well as an advanced list of all the modules and their variations appear in the advanced installation folder. ****************************************************************************************************** V Data Storage ****************************************************************************************************** This section discusses the way Zedd stores data, and is not on a need to know basis for those who do not plan to mess with the data directly. For the purpose of examples, it is assumed that the user has defined the object address as L1. As the object index starts at 1, the first object has a starting address of L1+16, and spans from that address to L1+31, a total of 16 bytes. An object at address L has the following data: Address Length Description ------------------------------------------- L 2 Bytes Signed X position in sub pixels L+2 2 Bytes Signed Y position in sub pixels L+4 2 Bytes Signed X velocity in sub pixels per frame L+6 2 Bytes Signed Y Velocity in sub pixels per frame L+8 1 Byte Unsigned Width in Pixels L+9 1 Byte Unsigned Height in Pixels L+10 1 Byte Unsigned Mass L+11 1 Byte X Axis locked Flag L+12 1 Byte Y Axis locked Flag L+13 1 Byte Sprite buffer offset L+14 1 Byte Unsigned Frictional Constant L+15 1 Byte Free space for user There is also global data that is stored in the space from L1 to L1+15, although much of it is free for the user. Adress Length Description --------------------------------------------- L1 1 Byte Unsigned Number of current objects L1+2 2 Byte Signed Global X Acceleration in sub pixels per frame per frame L1+4 2 Byte Signed Global T Acceleration in sub pixels per frame per frame L1+6 - L1+15 10 Bytes Free sace for user ****************************************************************************************************** VI External Libraries ****************************************************************************************************** One of the advanced features that Zedd offers is the ability to incorporate external libraries into the physics engine. Each library will be able to work alongside each other, with little to no interference. You can use some of the libraries already provided, or if you feel you know the Zedd engine well enough, write some of your own! Either way, all libraries are accessed, initialized, and controlled in the same way. This is some example pseudocode using the standard ROPE library, and details when the subprograms should be placed, as well as how it should be initialized. :.My Program //Start of your program :L1+400->GDB1OB //define the area the Rope engine will use for its data :L4->GDB0VR //Zedd's temporary variables are shared by all libraries :LoadZ() //Load the Zedd engine :LoadR() //Load the Rope engine : :NORMAL GAME CODE //Whatever your game is : :Return //Exit Game : :prgmZEDD1 //ZEDD Subprogram code :prgmSROPE //The rope subprogram :LBL CallZ //Mandatory Callback Function :Return //Return Callback Function After you have successfully entered and initialized your engine, you can use any of the functions that the library provides. Libraries might take control of objects, change elasticity or friction, add behaviors such as springs or ropes, and countless other possibilities. Zedd is, after all, just a collision solver. With the ability to implement dynamic libraries, Zedd can be the basis for all types of physics games. ****************************************************************************************************** VII Callback Function ****************************************************************************************************** Some features would be difficult to achieve by normal means. Say you wanted to apply a force to every object on the screen, it would be a bit complicated to set up a loop yourself, and mess with the index offsets and such, things would just get complicated. Plus, the Zedd engine already loops through the objects once, why would you want to do it a second time? The answer is the callback function. The Callback function is a unique piece of code that the user designs. When the Zedd simulation frame is calculated, your code is automatically applied to every object. No need for messing with loops or memory locations, every object will be able to be affected by the code you place in the callback function. Several libraries are also custom made for being included in the callback method, and include such global effects like water buoyancy, explosions, vacuums, and many other possibilities. Now, one very important thing to remember when writing code for the callback function is this: You will be working not with memory locations, but the variables A-Z. Even though your main program uses these variables, within the callback function, they represent entirely different values; Values that relate to the objects. Here is a list of some of the important variables and what they represent: Variable Description ---------------------------------------------- X,Y The X and Y position in sub pixels S,T The X and Y position in pixels A,B The X and Y velocity in sub pixels M Mass All other variables that are associated with the object can be accessed via {L+#} where L is the variable L, and # is the index offset found in the object data chart above. Now REMEMBER, these variables do not represent the values of any specific object, but rather the values of every object. If you include A+1->A in your callback function, EVERY OBJECT will have their X velocity increased by 1 every frame. An example of a simple callback function looks like this: :.My Program //Start of your program :NORMAL LOADING CODE //Loading the engine :NORMAL GAME CODE //Whatever your game is : :Return //Exit Game : :prgmZEDD1 //ZEDD Subprogram code :LBL CallZ //Mandatory Callback Function :If S>48 //If the object is to the right of the screen :A-1->A //accelerate to the left :Else //else :A+1->A //accelerate to the right :End //End :Return //Return Callback Function This simple callback function accelerates object towards the center of the screen; a simple effect, but one that would be much more complicated without the callback function feature. You also have the option of placing special callback libraries inside of the Callback Function to enable their special features ****************************************************************************************************** VIII World Collision ****************************************************************************************************** Another built in feature that Zedd supports is world collision for the objects. This allows objects to collide with static objects represented by the screen bounds, tilemaps of variable size, or even static images. The way world handling is handled by Zedd is by default a configurable tilemap, but using the modular construction the user has access to several more types of collision that can conform to any games needs. There are two types of modules associated with world collision. The first is the routine for determining which pixels on the screen are solid or not. By default the Zedd engine uses a tilemap module for determining solidity, and it takes these global inputs: Variable Name Definition ------------------------------------------------------------------------------------------------------- GDB0TM Address Location of tilemap, with Tilemaps following left->right, top->bottom format GDB0CL Collision switch point. Tiles