GMFileSystem Doc 1 4

5/26/2018 GMFileSystem Doc 1 4

1/47

1. GMFileSystem

GMFileSystem is an extensions for GameMaker studio. It allows users to ignore the(arbitrary) sandbox

restrictions set up by yoyogames. GMFileSystem tries to look like! gamemaker"s built in functions# $s

such one of the core components is to make the functions as transparent as possible% the functions.

&his means no helpfile should be necessary# the help comes from the GM manual.&here are some differences# some impro'ements as well as extra restrictions. &hese differences will be

discussed during this small manual. $lso some performance notes will be explained as well as an

indication of how GMFileSystem works behind the schemes. &he final parts of the manual contain a

reference list# where each function is uickly explained (and the corresponding function inside the

manual is shown).

pdates to the GMFileSystem extension can always be found at the GM* topic

(http+,,gmc.yoyogames.com,index.php-showtopic/01/23 ). GMFileSystem is licensed under the new

4S5 license% the source is a'ailable on google (http+,,gm6filesystem.googlecode.com, ).

GMFileSystem consist of se'eral parts# those parts can be separated at will# as to pre'ent unnecessary

file si7e increase. *urrent the parts are as following

GMFile GMResource GMIni GMXML

Size

(Kb)

288 2/88 298 :;8

Use

s

File system functions

&ext file functions

binary file functions

Sprite management

4ackground

management

Sound management

Image sa'ing

Ini handling


2/47

Table of Contents

:.GMFileSystem..........................................................................................................................................:

2.Manual....................................................................................................................................................0

?.GMFile.....................................................................................................................................................1

?.:.&ext files...........................................................................................................................................1

?.2.>ocality.............................................................................................................................................3

?.?.4inary files.......................................................................................................................................3

?.9.@rror Aandling.................................................................................................................................;

?./.File System.....................................................................................................................................:8

9.GM=esource..........................................................................................................................................::

9.:.Internal beha'iour.........................................................................................................................::

9.2.>oading resources..........................................................................................................................:2

9.?.@xporting resources.......................................................................................................................:2

/.GMIni.....................................................................................................................................................:9

/.:.GM6like interface...........................................................................................................................:9

/.2.Multiple ini file interface...............................................................................................................:90.GM..................................................................................................................................................:0

0.:.&hree datatypes.............................................................................................................................:0

0.2.>oading an xml file ........................................................................................................................:1

0.?.Iterating o'er elements.................................................................................................................:3

0.9.@lement access..............................................................................................................................:;

0./.*hanging xml tree6structure..........................................................................................................28

0.0.$ttribute access.............................................................................................................................2:

1.=eference..............................................................................................................................................22

FSBfileBtextBopenBread(fname).....................................................................................................22

FSBfileBtextBopenBwrite(fname)....................................................................................................22

FSBfileBtextBopenBappend(fname)................................................................................................22

FSBfileBtextBreadBstring(file).........................................................................................................22

FSBfileBtextBreadBchar(file# number).............................................................................................22

FSBfileBtextBreadBreal(file)............................................................................................................22

FSBfileBtextBreadln(file).................................................................................................................2?

FSBfileBtextBunread(file)................................................................................................................2?

FSBfileBtextBwriteBstring(file# string).............................................................................................2?

FSBfileBtextBwriteBreal(file# number)............................................................................................2?

FSBfileBtextBwriteln(file)................................................................................................................2?

FSBfileBtextBeof(file)......................................................................................................................2?

FSBfileBtextBfail(file).......................................................................................................................29FSBfileBtextBbad(file)......................................................................................................................29

FSBfileBtextBgood(file)....................................................................................................................29

FSBfileBtextBsetBfail(file# fail).........................................................................................................29

FSBfileBtextBsetBfail(file# bad)........................................................................................................29

FSBfileBbinBopen(fname# mode)....................................................................................................29

FSBfileBbinBreadBbyte(file)............................................................................................................2/

FSBfileBbinBreadBword(file)...........................................................................................................2/

FSBfileBbinBreadBdword(file).........................................................................................................2/


3/47

FSBfileBbinBwriteBbyte(file# 'alue).................................................................................................2/

FSBfileBbinBwriteBword(file# 'alue)................................................................................................2/

FSBfileBbinBwriteBdword(file# 'alue).............................................................................................2/

FSBfileBbinBwriteBbyte(file# 'alue).................................................................................................20

FSBfileBbinBsi7e(file).......................................................................................................................20

FSBfileBbinBposition(file)................................................................................................................20

FSBfileBbinBseek(file# pos)..............................................................................................................20FSBfileBbinBseek(file# offset# rel)....................................................................................................20

FSBdirectoryBexists(dir)..................................................................................................................20

FSBdirectoryBcreate(dir).................................................................................................................21

FSBdirectoryBdelete(dir).................................................................................................................21

FSBfileBexists(filename)..................................................................................................................21

FSBfileBdelete(filename).................................................................................................................21

FSBfileBrename(filename# newname)............................................................................................21

FSBfileBcopy(filename# newname).................................................................................................21

FSBfileBattributes(filename)...........................................................................................................23

FSBfileBfindBfirst(mask# attributes)................................................................................................23FSBfileBfindBnext()..........................................................................................................................23

FSBfileBfindBclose().........................................................................................................................23

FSBmaxBopenBfile()........................................................................................................................23

FSBsetBworkingBdirectory(dir).......................................................................................................23

FSBsetBgmBsa'eBarea(dir)..............................................................................................................2;

FSBcleanBtemporary()....................................................................................................................2;

FSBgetBuniueBfilename(dir# ext)..................................................................................................2;

FSBspriteBadd(fname# numb# remo'eback# smooth# xorig# yorig).................................................2;

FSBspriteBreplace(ind# fname# numb# remo'eback# smooth# xorig# yorig)....................................2;

FSBbackgroundBreplace(ind# fname# remo'eback# smooth)..........................................................?8

FSBbackgroundBadd(fname# remo'eback# smooth)......................................................................?8FSBsoundBreplace(ind# fname# kind# preload)................................................................................?8

FSBsoundBadd(fname# kind# preload)............................................................................................?8

FSBbackgroundBsa'e(ind# fname)..................................................................................................?8

FSBbackgroundBsa'eBad'(ind# fname# param)..............................................................................?:

FSBspriteBsa'e(ind# subimg# fname)...............................................................................................?:

FSBspriteBsa'eBad'(ind# subimg# fname# param)..........................................................................?:

FSBscreenBsa'e(fname)..................................................................................................................?:

FSBscreenBsa'eBad'(fname# param)..............................................................................................?:

FSBscreenBsa'eBpart(fname# x# y# w# h)..........................................................................................?2

FSBscreenBsa'eBpartBad'(fname# x# y# w# h# param)......................................................................?2FSBsurfaceBsa'e(id# fname)............................................................................................................?2

FSBsurfaceBsa'eBad'(id# fname# param)........................................................................................?2

FSBsurfaceBsa'eBpart(id# fname# x# y# w# h)....................................................................................??

FSBsurfaceBsa'eBpartBad'(id# fname# x# y# w# h# param)...............................................................??

FSBd?dBmodelBload(ind# fname)...................................................................................................??

FSBd?dBmodelBsa'e(ind# fname)...................................................................................................??

FSBiniBopen(fname)........................................................................................................................??

FSBiniBclose()..................................................................................................................................?9


4/47

FSBiniBreadBstring(section# key# def)..............................................................................................?9

FSBiniBreadBreal(section# key# def).................................................................................................?9

FSBiniBwriteBstring(section# key# 'al).............................................................................................?9

FSBiniBwriteBreal(section# key# 'al)................................................................................................?9

FSBiniBkeyBexists(section# key).......................................................................................................?/

FSBiniBkeyBdelete(section# key).....................................................................................................?/

FSBiniBsectionBexists(section)........................................................................................................?/FSBiniBsectionBdelete(section).......................................................................................................?/

FSBiniBopenBext(ini# fname)...........................................................................................................?/

FSBiniBcloseBext(ini).......................................................................................................................?/

FSBiniBreadBstringBext(ini# section# key# def).................................................................................?0

FSBiniBreadBrealBext(ini# section# key# def)....................................................................................?0

FSBiniBwriteBstringBext(ini# section# key# 'al).................................................................................?0

FSBiniBwriteBrealBext(ini# section# key# 'al)....................................................................................?0

FSBiniBkeyBexistsBext(ini# section# key)..........................................................................................?1

FSBiniBkeyBdeleteBext(ini# section# key).........................................................................................?1

FSBiniBsectionBexistsBext(ini# section)...........................................................................................?1FSBiniBsectionBdeleteBext(ini# section)..........................................................................................?1

FSBxmlBopen(fname)......................................................................................................................?1

FSBxmlBopenBext(fname# whatespace).........................................................................................?3

FSBxmlBclose(xml)..........................................................................................................................?3

FSBxmlBgetBnodeBtype(xml# node)................................................................................................?3

FSBxmlBnodeBmakeBelement(xml# node)......................................................................................?3

FSBxmlBsameBnode(nodeBleft# nodeBright)..................................................................................?3

FSBxmlBrootBelement(xml)............................................................................................................?3

FSBxmlBnumBelem(xml# parentBnode)..........................................................................................?;

FSBxmlBnumBnode(xml# parentBnode)..........................................................................................?;

FSBxmlBelemBfirst(xml# parentBnode)...........................................................................................?;FSBxmlBelemBlast(xml# parentBnode)............................................................................................?;

FSBxmlBelemBnext(xml# elem).......................................................................................................?;

FSBxmlBelemBpre'(xml# elem).......................................................................................................98

FSBxmlBnamedBelemBfirst(xml# parentBnode# name)...................................................................98

FSBxmlBnamedBelemBlast(xml# parentBnode# name)...................................................................98

FSBxmlBnamedBelemBnext(xml# elem)..........................................................................................98

FSBxmlBnamedBelemBpre'(xml# elem)..........................................................................................98

FSBxmlBnodeBfirst(xml# parentBnode)...........................................................................................9:

FSBxmlBnodeBlast(xml# parentBnode)............................................................................................9:

FSBxmlBnodeBnext(xml# node).......................................................................................................9:FSBxmlBnodeBpre'(xml# node).......................................................................................................9:

FSBxmlBfindBelem(xml# path).........................................................................................................9:

FSBxmlBfindBelem(xml# parentBelem# path)..................................................................................92

FSBxmlBparentBelem(xml# node)...................................................................................................92

FSBxmlBgetBelemBname(xml# elem)..............................................................................................92

FSBxmlBgetBelemBdata(xml# elem)................................................................................................92

FSBxmlBgetBnodeBrawBdata(xml# node)........................................................................................92

FSBxmlBsetBelemBname(xml# elem# name)...................................................................................9?


5/47

FSBxmlBgetBelemBdata(xml# elem# 'al)..........................................................................................9?

FSBxmlBsetBnodeBrawBdata(xml# node# 'al).................................................................................9?

FSBxmlBinsertBbeginBelem(xml# parentBelem# name# 'alue)........................................................9?

FSBxmlBinsertBendBelem(xml# parentBelem# name# 'alue)...........................................................9?

FSBxmlBinsertBelem(xml# parentBelem# afterBnode# name# 'alue)...............................................99

FSBxmlBinsertBbeginBnode(xml# parentBelem# type# 'alue).........................................................99

FSBxmlBinsertBendBnode(xml# parentBelem# type# 'alue)............................................................99FSBxmlBinsertBelem(xml# parentBelem# afterBnode# type# 'alue).................................................99

FSBxmlBdeleteBnode(xml# parentBelem# node).............................................................................9/

FSBxmlBdeleteBnode(xml# parentBnode).......................................................................................9/

FSBxmlBnumBattributes(xml# elem)...............................................................................................9/

FSBxmlBgetBattribute(xml# elem# name)........................................................................................9/

FSBxmlBsetBattribute(xml# elem# name# 'alue)..............................................................................9/

FSBxmlBdeleteBattribute(xml# elem# name)...................................................................................90

FSBxmlBattributeBfirst(xml# parentBelem).....................................................................................90

FSBxmlBattributeBlast(xml# parentBelem)......................................................................................90

FSBxmlBattributeBnext(xml# attribute)...........................................................................................90FSBxmlBattributeBpre'(xml# attribute)...........................................................................................90

FSBxmlBattributeBgetBname(xml# attribute)..................................................................................91

FSBxmlBattributeBgetB'alue(xml# attribute)..................................................................................91


6/47

2. Manual

5uring this chapter the different parts of GMFileSystem will be discussed. @ach part has its own files C

can be completely separated from the other parts C the extension without making those other parts

no longer work. &o remo'e a part simply delete all files that belong to the part from the extension in

the resource tree (generally all files belonging to the same part ha'e the same name# Dust differentextensions).

*urrently the parts implemented are as following+

GMFile GMResource GMIni GMXML

Size

(Kb)

288 2/88 298 :;8

Uses File system functions

&ext file functions

binary file functions

Sprite management

4ackground

management

Sound management

Image sa'ing

Ini handling @documents! get the mydocuments! folder in windows 'ista.


7/47

. GMFile

Si7e+ 288Jb

Files+ GMFile.dll

GMFile handles all basic file management functions. &ext file functions (reading writing)# binary file

functions (with some extra strength)# and generic filesystem functions (copying files# deleting,creating

directories C files).

First the text file functions will be handled# followed by the binary functions% after that some

information will be gi'en on error handling (as this is the same for both text C binary files). Finally the

functions of filesystem will be shortly discussed

.1. !e"t #iles

Function Description

File = FS_file_text_open_read(fname) Opens file for readingFS_file_text_read_string(file) Reads contents of current line as string

FS_file_text_read_char(file, number) Reads a number of characters

FS_file_text_read_real(file) Reads a number from file

FS_file_text_unread(file) Unreads a character.

FS_file_text_readln(file) Goes to the next line

File = FS_file_text_open_append(fname) Opens the file for writing at the end

File = FS_file_text_open_write(fname) Opens the file for writing

FS_file_text_write_string(file, string) Writes a string to the fileFS_file_text_write_read(file, number) Writes a number to a file

FS_file_text_writeln(file) Writes a newline

FS_write_flush(file) Flushes the buffer to the hard drive

FS_set_locality(localstring) Sets locality

>ocality for text files is handled correctly. (possix file systems will ha'e a >K byte at the ends of a line#

windows based ha'e *=L>K). Further locality regarding numeric 'alues will be handled in the next

paragraph.

&he text files act almost exactly as GameMaker"s built in functions# in the part reference > File

Handling > Files. hen reading a numeric 'alue from a file the parser will skip leading spaces# and

ends the moment a number is no longer a number. &his allows you to ha'e multiple numbers

separated by spaces on a line.

&he function FS_file_write_flush() is added+ to allow you to force writing of the buffer to the hard

dri'e. $nother extra function is FS_file_text_read_char() . &his function reads a gi'en number of

characters E or until an end of line character is found. Finally the function FS_text_unread() is added.


8/47

&his function allows you to unread! characters+ so to mo'e back in the file.

.2. Locality


FS_set_locality(localstring) Sets locality

hen the program starts the locality is set to t$e current system locality (c$an%e& #rom 1..'). &his is

different from the standard! c6locality# though more in line with GM C other office programs. &he

function gi'en abo'e allows you to change the locality manually during program execution.

&here some 'alue for localstring that work

:) pro'iding an empty string sets locality to the system locality

2) pro'iding *! sets the locality to original c6style

?) Hn windows (when the 5>> is compiled with NS) there are a lot of locality strings. &hese ha'e

the form >anguageB*ountry.*odeage. (I@+ GermanBGermany.:2/2# or @nglishBnited

States.:2/2). $ll 'alues can be found at

http+,,www.mydigitallife.info,ansi6code6page6for6windows6system6locale6with6identifier6constants6and6strings,

&he function returns whether the locale set was successful# in effect whether the locale is installed on

the user"s *. (*! and ! should always work).

.. inary #iles


File=FS_file_bin_open(fname, mode) Opens a file for writing or reading

FS_file_bin_read_byte(file) Reads a byte from the file

FS_file_bin_read_word(file) Reads a short ! bytes" from the file

FS_file_bin_read_dword(file) Reads a long # bytes" from the file

FS_file_bin_write_byte(file, value) Writes a byte to the file

FS_file_bin_write_word(file, value) Write a short ! bytes" to the file

FS_file_bin_write_dword(file, value) Writes a long # bytes" to the file

FS_file_bin_size(file) Returns the si$e of the file

FS_file_bin_position(file) Returns the current position

FS_bin_see(file, pos) Sets the position

FS_bin_see_relative(file, offset, rel) Sets the position relative to the target

&he binary files work exactly the same as the build in binary functions reference > File Handling >

Binary Files. &here are some extra features added to the binary functions to impro'e usage of binary

files.

First of are the impro'ement in binary file reading C writing.

FS_file_bin_read_word, FS_file_bin_write_word&hese 2 functions allow one to read,write a 26


9/47

byte6'alue at once. (So instead of a 'alue between 862//# the 'alue can be between 860/#/?/). &he

format in which the bytes are stored is depending on the system used to read,write the bytes. (>ittle

endian on intel pcs# big endian on other systems). $s such you should take a lot of care when writing a

file in 6say6 mac osx and reading it in windows.

FS_file_bin_read_dword, FS_file_bin_write_dwordSimilar to abo'e# but instead thse write a 96byte6

'alue at once. (So instead of a 'alue between 862//# the 'alue can be between 869#2;9#;01#2;/ ).

&he other impro'ement is the function FS_bin_seek_relative &his function allows more control o'er

setting the position. &he ?rdargument describes from what position the offset is calculated# it can ha'e

? 'alues+

8 6 relati'e to the beginning of the file (default operation# like in gamemaker)

: 6 relati'e to the end of the file

2 6 relati'e to the current position

.. *rror +an&lin%

File functions can easily gi'e errors. &he error handling is the same for both text as well as binary files.

here gamemaker only allows one to check if reading a file has reached the end6of6file#GMFileSystem allows for a lot more control. &hey do use the _text_part instead of _bin_because

GM"s also does.


FS_file_text_eof(file) Whether reading has reach the end of file

FS_file_text_fail(file) Failbit has been set

FS_file_text_bad(file) %adbit has been set

FS_file_text_good(file) Whether any of previous & bits has been set

FS_file_text_set_fail(file, fail)

Sets the failbit to 'fail(FS_fail_text_set_bad(file, bad) Sets the failbit to 'bad(

FS_file_text_eof() &his is an actual GM function# though it is also part of the group to handle

exceptions. =eturns true if filereading has reached end of file.

FS_file_text_fail() Means an exception happened. Aas three prime causes+ when opening a file this

exception happens if the file can"t be opened (isn"t there# something locked it out etc). hen reading

data it can happen if trying to read past end of file. $nd finally it can happen if you try to write bad

formatted data to a file.

FS_file_text_bad() Means the file has crashed. Main cause of this is when the file can"t be written to

anymore while it was opened. (I@ storage medium got remo'ed).FS_file_text_good() Means non of the abo'e states is set.

Hnly when good()returns true the functions actually work# otherwise they are simply ignored and a

default 'alue is returned. In case you wish to continue after the file6reading crashed (ie% you know the

storage medium got reconnected) you can set the fail and bad bits to true!


10/47

.,. File System

File system part handles all file management tasks. &he filesystem is almost a direct copy of the

functions inside reference > File Handling > File Systemthough some extra function from the main part

(reference > File Handling)# mainly the directory! functions.

Function DescriptionFS_directory_exists(dir) )ests if dir exists

FS_directory_create(dir) *reates directory and parent directories"

FS_directory_delete(dir) +eletes directory and all files,subdirectories

FS_file_exists(fname) )ests if fname exists

FS_file_delete(fname) +eletes file fname

FS_file_rename(fname, newname) Renames fname to newname

FS_file_copy(fname, newname) *opies fname to newname

FS_file_attributes(fname) Returns attributes of fname

FS_file_find_first(mas, attributes) Finds first file that satisfies mas- attributes

FS_file_find_next() Finds next file that satisfies mas- attributes

FS_file_find_close() Frees file find memory

FS_max_open_file() Returns maximum open files

&hese functions mostly work exactly the alike to the built in functions. ith three notable exceptions%

file_rename()can be used to mo'e files to another directory E simply pro'iding a different directory

will do this. (Kotice that for newname you will ha'e to pro'ide a full path).FS_file_attributes will po'ide many more attributes than those specified by gamemaker. (&hough

testing if a certain exists using FS_file_attributes("file") & fa_readonly fa_readonlyworks.

&he full attribute list can be found at MS5K ( :). $lso note that (like in gamemaker) for HSSIB&@B&@


18/47

3.. Iteratin% o-er elements

Functions Description

FS_xml_root_element(xml) Gets the root element

FS_xml_num_elem(xml, parent_node) Gets number of child elements under parent

FS_xml_elem_first(xml, parent_node) Gets the first element under parent4nodeFS_xml_elem_last(xml, parent_node) Gets the last element under parent4node

FS_xml_elem_next(xml, elem) Gets the next element

FS_xml_elem_prev(xml, elem) Gets the previous element

FS_xml_named_elem_first(xml,

parent_node, name)

Gets the first element with name 'name( under

parent4node

FS_xml_named_elem_last(xml,parent_node, name)

Gets the last element with name 'name( underparent4node

FS_xml_named_elem_next(xml, elem) Gets the next element with name 'name(

FS_xml_named_elem_prev(xml, elem) Gets the previous element

FS_xml_num_node(xml, parent_node) Gets number of child nodes under parent

FS_xml_node_first(xml, parent_node) Gets the first node under parent4node

FS_xml_node_last(xml, parent_node) Gets the last node under parent4node

FS_xml_node_next(xml, node) Gets the next node

FS_xml_node_prev(xml, node) Gets the previous node

FS_xml_find_elem(xml, pathstring) Finds an element based on a string0path

FS_xml_find_elem_under(xml, elem,

pathstring

Finds an element under the given element with the

specified path

FS_xml_parent_elem(xml, node) Gets the parent element of the given node

Iterating o'er elements works similar to maps. ith the main difference that the function do not

return a workable! 'alue (key)# but instead return a handle,id for the element. (hich can be

compared for euality# or used to get the name,'alue). &he iterating functions also need to know the

parent function.

If you know the name of an child element you can also iterate o'er only the elements with this name

(and if the name is uniue# getting the first element with this name ob'iously also gets &A@ element

with the name). &he BnodeB functions work o'er the nodes! where the BelemB functions only iterate

the elements under a certain node. $n example code to read and display below xml file+

$student% $name%/aul$name% $id%7889:;$id% $study%.0$study%$student%

var root_element FS_xml_root_element(xml)var cur_elem FS_xml_child_elem_first(xml, root_elem)


19/47

var num FS_xml_num_child_elem(xml, root_elem)

for (var num FS_xml_num_child_elem(xml, root_elem)< num % 8< n) = var name FS_xml_get_elem_name(xml, cur_elem)< var value FS_xml_get_elem_data(xml, cur_elem)< var str ">ode name? " @ name

Date post:	16-Oct-2015
Category:	Documents
Upload:	fabio-muller
View:	37 times
Download:	0 times

GMFileSystem Doc 1 4

Documents