 __ __ _____ _____               ____  __    __    
|  |  | __  |  _  |   ___ ___   |    \|  |  |  |   
|-   -|    -|   __|  |___|___|  |  |  |  |__|  |__ 
|__|__|__|__|__|                |____/|_____|_____|

Resource File
Current version:
XRP DLL 3.3

--Credits--

DLL
---
IsmAvatar

Original GML
------------
Nailog
Exploding Diamond Products

Producer
--------
Exploding Diamond Products

Example and Readme
------------------
Exploding Diamond Products


<<<Made for Game Maker>>>

NEWS---

12-9-05:
Seeded encryption added to verson 3.3.

12-4-05:
I've been given news that MPQ is copyrighted, therefor the file is changed
to XRP.

12-3-05:
New version (3.2) with .zip compression and decompression!
See very bottom of readme.

12-1-05:
MPQubed.  <- Ism thought of that one :) (MPQ3)
4 New functions!
One more is in the works (the ability to take all the files from a folder)
but will be released later.
<PUBLIC RELEASE MPQubed MPQ 3.0>

11-30-05:
MPQ Version 2.  Functions differently than Nailog's idea, hence "MPQ 2."


---Crediting---
You do not have to reference us in your credits.
However we would appreciate it if you did.
An image you may put in is in the data\images\
folder of this directory.
Thank you ^_^

---Installing---
Either merge "xrp.gm6" with your game or import "xrp.gml."


---FAQ---

1. What is XRP?

An XRP file (.xrp) is a file that contains all of your external resources.
Normally your resources are open to modification, stealing, and other bad
things that can cause problems.  With a XRP file though, you can
keep your files safe and sound inside one big file.

2. How easy is it to use?

Any intermediate person who knows GML should be able to use it properly.
It is well documented (see below) and has only a few un-complicated functions.

3. Is it free?

Yes, it is freeware.  Feel free to distribute it, as long as you do not 
modify the creator information.

4. Is it open-souce?

No.  The source will allow people access to .XRP files.

5. What does XRP stand for?

Xternal Resource Package.

6. You keep mentioning Items and Files. What is the difference?
 
None - an item is basically a file contained within the XRP. (by IsmAvatar)

7. Is the file compressed?

Yes.  The file uses zip compression.

8. Is the file or the files inside encrypted?

Yes.  The XRP file is encrypted to protect your files.

9. What are those other programs that come with it?

PACL, or PowerArchive Command Line, available at http://www.powerarchiver.com/download/#pacl
is a free program which compresses and decompresses files

10. What files must I include with my game for all the functions to work?

Both PA*.exe programs, xrp.dll, unrar3.dll, and xrpicon.ico.

11. I have a problem, error, or question!

Okay.

12. Oh right, question form, my bad.  How do I contact the XRP team?

If you have a problem, error, or question, you can contact me (EDP)
or IsmAvatar.  Check our GMC information for contact info.


---Information---
by IsmAvatar

All strings are actually pchars.
All calls are of type stdcall.
Error if any file cannot be accessed.
An error may cause involved files to corrupt.
The first item in an XRP file is index 0.
Folder names must end with a slash.
Wildcards are never permitted.

Index & Quick Reference:
_add, _compact, _count, _decrypt, _encrypt, _extract,
_fetch, _insert, _name, _numb, _remove, _set, _size

_set: set the XRP file
_encrypt: encrypt file with basic encryption scheme
_decrypt: decrypt file with basic encryption scheme
_add: append an item to the end of the file
_insert: insert an item into the file
_compact: append all files in a folder to end of file
_remove: remove an item from the file
_fetch: extract 1 item to a location
_extract: extrect ALL the items to a folder
_count: tell how many items there are
_numb: get the number of the item with given name
_name: get the name of an item
_size: get the [file]size of the item


_add(target : string) : real
Appends the target file to the end of the XRP file.
Uses the filename as the name.
Creates the XRP if it does not exist.
Increases the number of items by 1.
Speed: Medium, slower than _compact if using multiple files
>Returns the size of the written item
>Returns -1 if target does not exist.
>Error if XRP is corrupted.

_compact(folder : string) : real
Appends all files in the folder to end of XRP file.
Uses the filenames as the names.
Does not enter subfolders.
Creates the XRP if it does not exist.
Increases number of items by number of files in folder.
Speed: Faster than add

_count() : real
This information is contained in the first 4 bytes of XRP.
Speed: Instantanious
>Returns the number of items in the XRP file.
>Returns -2 if XRP file does not exist.
>Returns -1 if XRP file is smaller than 4 bytes.
>No errors, ever.

_decrypt(seed : real) : real
Decrypts the file with -1/0/+1 scheme.
You may use this function to encrypt instead,
and use _encrypt to decrypt.
Speed: Slow
>argument0: the seed (1-255) to decrypt
>Error if XRP does not exist.

_encrypt(seed : real) : real
Encrypts the file.
You may call this function multiple times,
and call _decrypt the same amount of times to decrypt.
Speed: Slow
>argument0: the seed (1-255) to encrypt
>Error if XRP does not exist.

_extract(folder : string) : real
Copies all the items in the XRP file to the folder.
Files will overwrite previously existing files.
If a file is not overwritten, it will remain.
Creates the folder if it does not exist.
>Returns the number of files extracted.
>Error if XRP does not exist or is corrupted.

_fetch(target : string; n : real) : string
Copies the n'th item from the XRP file into the target.
Target may be either a folder or a filename to overwrite.
Speed: Medium
>Returns item name. This is filename if target is folder.
>Error if XRP does not exist or is corrupted.
>Error if n is greater than or equal to number of items.

_insert(target : string; n : real) : real
Insert the target before the n'th item in the XRP file.
Uses the filename as the name.
Creates the XRP if it does not exist.
Increases the number of items by 1.
Speed: Medium
>Returns the size of the written item.
>Returns -1 if target does not exist.
>Error if XRP is corrupted.

_name(n : real) : string
Speed: Instantanious
>Returns the [file]name of the n'th item in the XRP file.
>Error if XRP does not exist or is corrupted.
>Error if n is greater than or equal to number of items.

_numb(name : string) : real
Searches the XRP file for the first item with given name.
Speed: Instantanious
>Returns the index of first item with given name.
>Returns -1 if no items have given name.
>Error if XRP does not exist or is corrupted.

_remove(n : real) : string
Rewrites the file without the n'th item.
Decreases the number of items by 1.
Speed: Medium
*Note* May not delete backup file it creates
>Returns the name of the removed item.
>Error if XRP does not exist or is corrupted.
>Error if n is greater than or equal to number of items.

_set(XRPfile : string) : real
Sets the XRP file referenced in all the other functions.
Speed: Instantanious
>Returns 1, always.
>No errors, ever - may cause errors in other functions.

_size(n : real) : real
Speed: Instantanious
>Returns the [file]size of the n'th item in the XRP file.
>Error if XRP does not exist or is corrupted.
>Error if n is greater than or equal to number of items.


Initializing the functions in GM:
xrp = "xrp.dll"
global.ADD = external_define(xrp,"_add",1,0,1,1)
global.COMPACT = external_define(xrp,"_compact",1,0,1,1)
global.COUNT = external_define(xrp,"_count",1,0,0)
global.DECRYPT = external_define(xrp,"_decrypt",1,0,0)
global.ENCRYPT = external_define(xrp,"_encrypt",1,0,0)
global.EXTRACT = external_define(xrp,"_extract",1,0,2,1,0)
global.FETCH = external_define(xrp,"_fetch",1,1,2,1,0)
global.INSERT = external_define(xrp,"_insert",1,0,2,1,0)
global.NAME = external_define(xrp,"_name",1,1,1,0)
global.NUMB = external_define(xrp,"_numb",1,0,1,1)
global.REMOVE = external_define(xrp,"_remove",1,1,1,0)
global.SET = external_define(xrp,"_set",1,0,1,1)
global.SIZE = external_define(xrp,"_size",1,0,1,0)


The XRP File Format Documentation:

Items {
 Name Length (1 byte) { Name }
 File Size { File }
}


---Other Functions---


xrp_associate: Set the icon for the XRP file (do not use this function)

xrp_compress: compress the XRP into a zip file, using PACL

xrp_decompress: decompress the XRP from a zip file
