 INFO
|
||
|
Sprite Candy comes with many additional commands to assist the creation of 2D games or -animations. These commands can be used to simplify your work and to keep your own code as clean as possible. New commands will be added on demand, so please feel free to send us your feedback and suggestions.
Hint: when using distance checks and collision commands with many objects at once or within a loop, you should do a simple x / y coordinate check before and use collision or distance checks if the objects are close enough only. This will avoid slowdowns and keep your game's performance as high as possible. Another good practice is to perform collision checks every second frame only, which can save up to 50% performance.
|
||
| | ||
|
USEFUL COMMANDS
|
||
|
|
||
| | ||
MISCELLANEOUS |
||
|
HUD_GetStats$
|
||
|
This command returns a text string containing useful realtime information like the current FPS count, as well as the number of surfaces, vertices, objects and effects used by Sprite Candy. Use this information to keep an eye on your game's performance.
|
||
| | ||
|
HUD_GetObjectType$
|
||
|
This command returns a string that describes the type of an object (text, image, shape etc.). It can be used with a button check, for example, to find out wether a text or an image button has been clicked. Returns:
Object_Handle%
|
||
| | ||
| | ||
|
HUD_GetObjectLayer
|
||
|
This command returns the Sprite Candy handle of the object's parent layer.
Object_Handle%
|
||
| | ||
|
HUD_CreateCopy
|
||
|
This command creates an exact copy of the specified object and can be used to duplicate objects easily. If no offset is specified, the copy will be placed at the source object's position.
Object_Handle%
offset_x% , offset_y%
|
||
| | ||
|
HUD_AlignToScreen
|
||
|
Using this command, you can position an object at a specified screen position, regardless of the current screen resolution.
Object_Handle%
xAlign$
Hint: You can also use offsets: "CENTER+50" or "RIGHT-25", for example!
yAlign$
Hint: You can also use offsets: "CENTER+50" or "BOTTOM-50", for example!
|
||
| | ||
|
HUD_FaceObject
|
||
|
This command will turn the source object so that if faces the target object with it's negative y-axis (top). You can also use the similar FX-command to turn an object smoothly to another.
SourceObject% , TargetObject%
|
||
| | ||
|
HUD_ObjectExists
|
||
|
This command can be used to check wether an object still exists or not. Use it if you applied the FX_AutoRemove effect to an object and need to know if this object has been deleted already or not, for example. Returns TRUE if the specified object exists, otherwise FALSE.
Object_Handle%
|
||
| | ||
|
HUD_RippleObject
|
||
|
You can remove a ripple effect by using HUD_RippleObject ( Object_Handle, 0 )
Object_Handle%
width#
The 'width' or frequency of the wave. Higher values will produce narrow waves that are repeated more often, where lower frequencies produce big and long waves. For good results, use a value between 1 and 5, for example.
height#
offset#
|
||
| | ||
COLLISION CHECK |
||
|
HUD_GetDistance
|
||
|
Returns the distance, in pixels, between to specified points.
x1% , y1% , x2% , y2%
|
||
| | ||
|
HUD_GetPointLineDistance
|
||
|
Returns the distance, in pixels, between a point and a line. Can be used to check if a laser hits an object, for example.
px%, py%
x1% , y1% , x2% , y2%
|
||
| | ||
|
HUD_GetObjectDistance
|
||
|
Returns the distance, in pixels, between two objects' center points. If the objects are placed on different layers that are scaled or rotated differently, the objects' coordinates are transformed automatically from one layer's coordinate system to the other.
Object_Handle1% , Object_Handle2%
|
||
| | ||
|
HUD_ObjectHitsPoint
|
||
|
Returns TRUE or FALSE. Indicates if a specified x / y coordinate is inside an object's boundaries, also if the object has been rotated. Can be used with MouseX() and MouseY(), for example, to check if the mouse is placed over an object. This command uses the coordinate system of the object's parent layer (which can differ from absolute screen coordinates when the layer is rotated or scaled).
Object_Handle%
x% , y%
SourceLayer%
Note: the coordinate systems of layers and absolute screen coordinates are all the same as long as HUDs and layers are not rotated or scaled. In this case you won't need this parameter. If a layer has been scaled or rotated, however, the coordinate systems of two layers may be different, or differ from absolut screen coordinates then. In this case, the x / y - coordinate must be converted to the object layer's coordinate system.
|
||
| | ||
|
HUD_ObjectHitsObject
|
||
|
Returns TRUE or FALSE. Indicates if the boundaries of two objects (texts, images, shapes etc.) intersect each other. This command also works with rotated objects, but is faster when used with non-rotated objects, of course.
Object_Handle1% , Object_Handle2%
|
||
| | ||
|
HUD_LinesIntersect
|
||
|
Returns TRUE or FALSE. Indicates if two lines intersect each other. The exact point of intersection will be stored within two globals named SC_IntersectedX and SC_IntersectedY.
x1% , y1% , x2% , y2%
x3% , y3% , x4% , y4%
|
||
| | ||
|
COLLISION SHAPES |
||
To give the possibility for more precise collision checks with irregular shaped objects, Sprite Candy supports collision shapes. A collision shape is a virtual polygon shape around an object. Such a shape is built by single points that you can define. Collision shapes can be added to any object (and also be removed again) at any time - either point by point or loaded from a point data file. After attaching a collision shape to an object, you can test if a certain point is inside this shape, or if two shapes overlap, for example. Once you created a collision shape for an object, Sprite Candy will move, scale and rotate it automatically to always fit the object that it has been attached to.
Sprite Candy includes a comfortable shape editor to easily create collision shapes for your images. You can load and attach collision shapes to objects at any time.
|
||
| | ||
|
HUD_AddCollisionPoint
|
||
|
This command adds a point to an object's collision shape, where 0,0 is always the upper-left corner of the object. All points of the collision shape are connected in the order they have been created. Collision shapes are invisible by default. You can display the collision shape of an object using HUD_DrawCollisionShapes( ).
x% , y%
|
||
| | ||
|
HUD_CopyCollisionShape
|
||
|
Using this command you can copy the entire collision shape of an object to another one.
Target_Object%
Source_Object%
|
||
| | ||
|
HUD_LoadCollisionShape
|
||
|
This command loads a shape data file (as created with the Sprite Candy Shape Editor, for example) and attaches this shape to the specified object. After loading a collision shape to an object, you can still add points manually using HUD_AddCollisionPoint( ), for example.
Object_Handle%
filename$
|
||
| | ||
|
HUD_ClearCollisionShape
|
||
|
This command clears (removes) all collision shape points of an object. Use it to free unused collision shapes (saves performance) or to clear an existing one if you want to build a new shape for this object.
Object_Handle%
|
||
| | ||
|
HUD_ShiftCollisionShape
|
||
|
This command moves (shifts) all points of an object's collision shape at a specified amount of pixels. Use it to adjust a shape if you notice that a created or loaded shape does not fit exactly to an object.
Object_Handle%
stepx% , stepy%
|
||
| | ||
|
HUD_DrawCollisionShapes
|
||
|
Use this command to display the collision shape of a certain object (or all objects).
Since this function uses common 2D drawing commands, it must be placed after RenderWorld and before Flip. Otherwise you won't see it's results. Use it for test purposes only.
Object_Handle%
R% , G% , B%
|
||
| | ||
|
HUD_CollisionShapeHitsPoint
|
||
|
Use this command to check if a certain x/y coordinate is inside an object's collision shape or not.
Returns:
Object_Handle%
x% , y%
Layer_Handle%
Use '0' if the specified coordinate is an absolute point on the screen.
|
||
| | ||
|
HUD_CollisionShapesOverlap
|
||
|
Use this command to check if the collision shapes of two objects intersect or not.
This command detects if the lines between the collision points are intersected by the lines of another shape, so it will only detect a collision when at least two collision shape lines cross each other - it will not detect a collision when one object is placed completely inside the other one, for example.
Returns:
Object1_Handle% , Object2_Handle%
|
||
| | ||
X-PRESSIVE.COM is a label and working title of Mike Dogan, est. 1999
All artwork, including graphics, text, images and sounds are property of Mike Dogan, X-PRESSIVE.COM. Trademarks belong to their respective owners. All rights reserved.