Alex "Y_Less" Cole's properties add-on v0.1
0) Contents:
0. Contents
1. IMPORTANT! (legal gumph)
2. About
3. Changelog
4. Technical data
4.0 Structures
4.1 Functions
4.2 Definitions
4.2.0 Callback inserts
4.2.1 Internal defines
4.2.2 Customizable defines
5. Use
5.0 Integration
5.1 Array
5.2 Types
5.2.0 LG_NOT_SPECIAL
5.2.1 LG_MONEY_AREA
5.2.2 LG_FORBIDDEN
5.2.3 LG_SPECIAL_AREA
5.2.4 LG_NAMED_AREA
5.2.5 - 5.2.127 Area expansion
5.2.128 LG_MONEY_POINT
5.2.129 LG_AMMU
5.2.130 LG_BANK
5.2.131 LG_PROPERTY
5.2.132 LG_SPECIAL_POINT
5.2.133 - 5.2.255 Point expansion
5.3 Parameters
5.3.0 LG_NO_CHECKPOINT
5.3.1 LG_NAME
5.3.2 LG_INTERIOR
5.3.3 LG_CP_STAY
5.3.4 LG_DEFAULT
5.3.5 LG_SELL
5.4 Teams
5.5 Options (OPTION_1 and OPTION_2)
5.6 Links
1) IMPORTANT! (legal gumph):
This code is protected under the GPL Open Source license: http://opensource.org/licenses/gpl-license.php
(c) 2006 Alex "Y_Less" Cole
2) About:
Alex "Y_Less" Coles properties code. I wrote this after looking at the LVDMod code (on which this is theoretically based however all the code is written from the ground up (all completely original code). While a pioneering piece of code (based on it's popularity and originality) it wasn't very easy to code with (lots of diverse arrays, defines limiting flexibility and properties and specials split in a single array) so I decided to write my own. The original idea was basically recode the system using an enum to keep things together and set the type based on a parameter rather than position (so you could mix up properties and others). I also didn't like the way they used 999 when there was a perfectly good INVALID_PLAYER_ID but that was just personal perference. I also wanted to redesign the spawn weapon system in the same veign.
This was also designed with ease of portability in mind so I made it as a psudo include file and made it easy to integrate.
3) Changelog:
v0.1:
Initial release
4) Technical data:
4.0) Structures:
There are three enum structures in use currently, one for properties data, one for weapons data and one for last checkpoint. In each the elements are prefixed to reduce conflits however this is not guaranteed (and can't be really):
enum LG_MAIN
{
MNAME[32],
Float:MAREA_MIN_X,
Float:MAREA_MAX_X,
Float:MAREA_MIN_Y,
Float:MAREA_MAX_Y,
Float:MCP_X,
Float:MCP_Y,
Float:MCP_Z,
Float:MCP_S,
MOPTION_1,
MOPTION_2,
MSPECIAL,
MTEAMS,
MOWNER,
MLINKS[16]
}
enum LG_LAST
{
LTYPE,
Float:LLAST_X,
Float:LLAST_Y,
Float:LLAST_Z,
Float:LLAST_S
}
enum LG_WEAPONS
{
WNAME[32],
WWEAPON,
WAMMO,
WPRICE
}
4.1) Functions:
The functions are as follows:
LGConnect(playerid)
This function is called upon player connecion, sets certain variables.
LGGetCurCP(playerid)
Returns the players current area (-1 if they're not in a system handled area). Note, if you don't use this function in your script the compiler will throw up a warning, just ignore this.
LGCP(playerid, Float:x, Float:y, Float:z, Float:size)
Sets a checkpoint by first destroying the old, making a new one the correct size at the location of the player then moving it. (Attempts to bypass SAMP bugs).
LGDisconnect(playerid)
This function is called upon player disconnecion, resets certain variables.
LG_Property_Loop()
The main loop, handles most of the processing.
LGRequiredLast
Checks the last area is in the area of neighbors for the current area.
LGSetPlayerCheckpoint(playerid, Float:x, Float:y, Float:z, Float:size)
Replaces SetPlayerCheckpoint in your main code, allows other points to be placed (e.g. for races) without upsetting the script.
LGDisablePlayerCheckpoint(plyaerid)
Replaces DisablePlayerCheckpoint in your main code, allows for other points to be removed (e.g. for races) without upsetting the script.
dcmd_properties(playerid, text[])
Handles the /properties command.
LGValidCP(playerid, cptype)
Checks the player is in a checkpoint of type cptype.
dcmd_listweapons(playerid, text[])
Handles the /listweapons command.
dcmd_buyweapon(playerid, text[])
Handles the /buyweapon command.
LG_buyable_properties()
Counts the numbers of properties in the array.
LG_ret_owner(owner)
Returns a string version of the owner or "<none>" if none.
dcmd_buy(playerid, text[])
Handles the /buy command.
dcmd_sell(playerid, text[])
Handles the /sell command.
LGSpawn(playerid)
This function is called upon player spawning, gives them weapons.
dcmd_balance(playerid, text[])
Handles the /balance command.
dcmd_bank(playerid, text[])
Handles the /bank command.
dcmd_withdraw(playerid, text[])
Handles the /withdraw command.
LGCPCheck(playerid)
Handles checkpoint entry for the script.
LGParseCmd(playerid, cmdtext[])
Takes input commands and checks them against script commands.
LGIsNumeric(const string[])
Checks if a string is numeric, renamed for compatibility with other scripts.
4.2) Definitions:
4.2.0) Callback inserts:
LG_INIT_CODE
Code placed in OnGameModeInit to begin the script.
LG_CONNECT_CODE
Code placed in OnPlayerConnect to reset player data.
LG_ENTER_CP_CODE
Code placed in OnPlayerEnterCheckpoint to handle checkpoint entries.
LG_SPAWN_CODE
Code placed in OnPlayerSpawn to reset certain stats every spawn.
LG_DISCONNECT_CODE
Code placed in OnPlayerDisconnect to reset certain variables.
LG_COMMAND_CODE
Code placed in OnPlayerCommandText to handle script commands.
4.2.1) Internal defines:
LG_ALL_TEAMS
Used to show a point for all teams.
LG_NO_LAST
Used to indicate that there was no checkpoint shown before the current one (for returning to last).
LG_NO_LINK
Used for areas with no other areas affecting them
LG_INVALID_LAST
Used to indicate a player defined checkpoint rather than a script run checkpoint was the last one.
LG_NOT_TEAMS
Used to invert the team list, so all the teams listed will NOT be affected by an area. If a player is in multiple teams and any of those teams are in the not list, that player will not be affected.
4.2.2) Customizable defines:
LG_PAY_LOOPS
Number of half second intervals between each property payout.
5) Use:
5.1) Integration:
To integrate place the Callback inserts (section 4.2.0) in their relevant callbacks (notes in 4.2.0). At the top (or near the top) of your file place:
#include "LGdefines.pwn"
Below that put the array of properties and the array of weapons (as that uses the defines file) and below that place:
#include "LGfunctions.pwn"
The other requisite for integration in team scripts is a slight change to team definitions. If you want multiple teams to be able to use checkpoints the numbering on teams needs to be exponential from 1 rather than consecutive from 0. I.e.:
OLD NEW
TEAM_FIRST 0 1
TEAM_SECOND 1 2
TEAM_THIRD 2 4
TEAM_FOURTH 3 8
etc.
5.2) Array:
There are two arrays running the script, the properties array and the spawn weapons array. These are as follows (examples):
new gLGPoints[][LG_MAIN] =
{
// NAME AREA_MIN_X AREA_MAX_X AREA_MIN_Y AREA_MAX_Y CP_X CP_Y CP_Z CP_S OPTION_1 OPTION_2 SPECIAL TEAMS OWNER LINKS
{"24-7", -40.23, -12.90, -93.89, -72.65, -26.86, -89.50, 1003.54, 2.0, 0, 0, LG_BANK | LG_INTERIOR, LG_ALL_TEAMS, INVALID_PLAYER_ID, LG_NO_LINK},
{"Ammunation", 282.25, 300.58, -43.79, -29.18, 291.83, -39.36, 1001.51, 2.0, 0, 0, LG_AMMU | LG_INTERIOR, LG_ALL_TEAMS, INVALID_PLAYER_ID, LG_NO_LINK},
{"Sex Shop", -117.95, -97.16, -26.26, -5.13, -104.02, -21.47, 1000.71, 2.0, 20000, 2000, LG_PROPERTY | LG_INTERIOR, LG_ALL_TEAMS, INVALID_PLAYER_ID, LG_NO_LINK}
};
new gLGWepDat[][LG_WEAPONS] =
{
// NAME WEAPON AMMO PRICE
{"Flamethrower", 37, 20, 5000},
{"UZI", 28, 200, 1000}
};
These arrays both use the previously detailed enums to store the data, with the parameters listed above each.
gLGPoints:
To use the properties, save an area bounding your checkpoint for the trigger area (min x, max x, min y, max y) and a point for the checkpoint itself (cp_x, cp_y, cp_z) (if you don't want a cp these and the size can be 0.0). You also need a name (NAME) and a size (CP_S). The other parameters are more complex. TEAM, LINKS and OPTION_1/OPTION_2 are described later.
OWNER:
This is mainly used for internal storage, if you want an initial owner set this to something other than INVALID_PLAYER_ID, otherwise leave it as it is.
SPECIAL:
This determines both the type of point and it's parameters as detailed in the next section. Each point can (and must) have only one type, otherwise problems may arise, but as many parameters as wanted. Each parameter and the type are separated by a | as with the teams. E.g:
LG_MONEY_AREA | LG_NAME | LG_INTERIOR
These will explained in the next section but that is how to use them.
gLGWepDat:
This is a much more simple array, just a list of weapons available from ammunation.
NAME:
Name of the weapon, displayed in the list.
WEAPON:
Weapon id (not model id).
AMMO:
Amount of ammo to spawn with.
PRICE:
Price...
5.3) Types:
5.2.0) LG_NOT_SPECIAL:
Does nothing, just displays a checkpoint.
5.2.1) LG_MONEY_AREA:
Increases your money by a defined amount every defined period of time. The delay is defined by OPTION_1 in half seconds (i.e. OPTION_1 = 7 means 3.5 second intervals), the amount of increase is defined by OPTION_2.
5.2.2) LG_FORBIDDEN:
Prevents a player entering the area
5.2.3) LG_SPECIAL_AREA:
Script defined special area. To use place the following at the top of your mode, above the includes for this script:
#define LG_SPECIAL_AREA_CODE <function name>
Where <function name> is the name of a function within your script with the following parameters:
playerid, areaid
E.g:
#define LG_SPECIAL_AREA_CODE MySpecialFunction
// includes and arrys for script (and other code)
public MySpecialFunction(playerid, areaid)
{
// Code here
// No return currently
}
And where areaid is the id of the area the player defined by playerid just entered. So if you want something special not covered by the standard functions within your mode you can include it like this. If you have lots you can go off the areaid as well.
5.2.4) LG_NAMED_AREA:
Basically used for naming areas of the city. Different style text to using LG_NAME, also has no checkpoint. The LINKS property is used to define other square areas in the same part of town so if you pass from one of them to this one no name will display (a large number of rectangles are used to define some areas).
5.2.5 - 5.2.127) Area expansion:
Reserved for other area types.
5.2.128) LG_MONEY_POINT:
Same as money area only you must be in the checkpoint rather than the area.
5.2.129) LG_AMMU:
Defines the area as an ammunation, when you enter the checkpoint you can purchase weapons.
5.2.130) LG_BANK:
Defines the area as a bank, when you enter the checkpoint you can bank and withdraw money.
5.2.131) LG_PROPERTY:
Defines the point as a property you can purchase. The price is defined by OPTION_1, the reward by OPTION_2. The delay time is detailed elsewhere (section 4.2.2). If LINKS (also known as neighbors) are set (up to 16) this property will only be seen if you enter from a neighbor. This can be used so two identical property lines can be used to differentiate between entering a shop from, say, LV and from LS, so you can have two shops using the same interior but using different data lines depending on which city they're in. The upshot being you can sell the same shop separately in both LV and LS and have different owners for each (you may want to name the shops accordingly to avoid confusion).
5.2.132) LG_SPECIAL_POINT:
Same as LG_SPECIAL_AREA only uses LG_SPECIAL_POINT_CODE for its trigger (parameters are the same).
5.2.133) LG_TELEPORT:
This creates a teleport marker. The destinations are defined by LINKS, so you need to use a taret point as well. If you have more than one target players will be prompted to select where they want to go (up to a maximum of 16 destinations). The targets are referenced by their array index. OPTION_1 can be used to set a price for the teleport.
5.2.134) LG_TARGET:
This is a destination point for the LG_TELEPORT type. As this will never actually be triggered it is advised you set the area to 0.0 0.0 0.0 0.0, TEAMS to 0 and set LG_NO_CHECKPOINT this will more than ensure you never get a random checkpoint for anyone and will waste minimal processing as it will not be processed for anyone (due to TEAMS being 0). CP_X, CP_Y and CP_Z are obviously the destination however CP_S is now the angle you spawn at and OPTION_1 can be used to set an interior. The targets have no link to the teleport so you can go to there from as many places as you like.
5.2.135 - 5.2.255) Point expansion:
Reserved for other point types.
5.3) Parameters:
5.3.0) LG_NO_CHECKPOINT:
Parameter for not placing a checkpoint in an area, if this is set no checkpoint will appear.
5.3.1) LG_NAME:
Parameter for displaying the name of an area upon entry, if this is set the NAME parameter will be displayed.
5.3.2) LG_INTERIOR:
Parameter for defining a checkpoint as in an interior, if this is set the area check will check you are over 700 high.
5.3.3) LG_CP_STAY:
Parameter for keeping the current checkpoint shown on exit from its area, if this is set, after a checkpoint is triggered it will stay visible until another one is triggered.
5.3.4) LG_DEFAULT:
Parameter for making the checkpoint the one to show when no others are being, if this is set it will show from the start.
5.3.5) LG_SELL:
Parameter for property checkpoints for making them buy/sell only (no buying out), if this is set you have to sell a point before someone else can buy it.
5.4) TEAMS:
You can set a checkpoint for only certain teams. As the teams are bit mapped (that's the effect of the exponential numbering) you can set checkpoints for a list of teams by adding (or, more preferably, ORing) the teams. If you want it to be for any team use:
LG_ALL_TEAMS
If you want it for only TEAM_SECOND (from my example above) just put the following in the TEAMS coloumn:
TEAM_SECOND
If you want it for only teams FIRST and THIRD use:
TEAM_FIRST | TEAM_THIRD
(the | means boolean OR, read elsewhere for more info on that, trust me, it works)
If a player is in multiple teams, if ANY of those teams are in the list they will be affected by this area.
There is also an LG_NOT_TEAMS parameters (section 4.2.1). If this is set, e.g:
LG_NOT_TEAMS | TEAM_FIRST | TEAM_THIRD
Then all teams BUT the teams listed will be affected. The behaviour of this is the opposite to that of not having it, so if a player is in multiple teams (i.e. TEAM_ADMIN and another), if any of those teams are in the list they will NOT be affected. This is useful for admin only areas using LG_AREA_FORBIDDEN.
5.5) OPTIONS:
These have a number parameter, there are different uses for each number depending on the type of checkpoint, these are detailed in the explanations for the relevant types.
5.6) LINKS:
This is a list of other areas which affect the current area, it has different effects based on the area type, see individual types for more details. This is a 16 big array however for easy of use you can simply put LG_NO_LINK to not have any links and this will set all 16 parameters to -1.