Upload
fabio-muller
View
37
Download
0
Embed Size (px)
Citation preview
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
5/26/2018 GMFileSystem Doc 1 4
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/
5/26/2018 GMFileSystem Doc 1 4
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
5/26/2018 GMFileSystem Doc 1 4
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/26/2018 GMFileSystem Doc 1 4
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
5/26/2018 GMFileSystem Doc 1 4
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.
5/26/2018 GMFileSystem Doc 1 4
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.
5/26/2018 GMFileSystem Doc 1 4
8/47
&his function allows you to unread! characters+ so to mo'e back in the file.
.2. Locality
Function Description
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
Function Description
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
5/26/2018 GMFileSystem Doc 1 4
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.
Function Description
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!
5/26/2018 GMFileSystem Doc 1 4
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&@
5/26/2018 GMFileSystem Doc 1 4
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)
5/26/2018 GMFileSystem Doc 1 4
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