1 #LyX 2.0 created this file. For more info see http://www.lyx.org/
6 \use_default_options true
7 \maintain_unincluded_children false
9 \language_package default
14 \font_typewriter default
15 \font_default_family default
16 \use_non_tex_fonts false
23 \default_output_format default
25 \bibtex_command default
26 \index_command default
27 \paperfontsize default
31 \pdf_bookmarksnumbered false
32 \pdf_bookmarksopen false
33 \pdf_bookmarksopenlevel 1
48 \paperorientation portrait
64 \paragraph_separation indent
65 \paragraph_indentation default
66 \quotes_language english
69 \paperpagestyle default
70 \tracking_changes false
80 lsnes Lua functions reference
87 \begin_layout Standard
88 \begin_inset CommandInset toc
89 LatexCommand tableofcontents
96 \begin_layout Standard
97 \begin_inset Newpage pagebreak
103 \begin_layout Section
107 \begin_layout Standard
108 These tokens are special, and are expanded while the script is being loaded
111 \begin_layout Subsection
112 @@LUA_SCRIPT_FILENAME@@
115 \begin_layout Standard
116 Expanded to string token containing path and filename of this Lua script.
117 Handy for referencing other lua scripts or resources that are relative
121 \begin_layout Standard
122 In practicular, this is suitable to be passed as base argument of various
123 functions like loadfile, dofile, resolve_filename, gui.bitmap_load, gui.bitmap_lo
124 ad_png and gui.bitmap_load_pal.
127 \begin_layout Section
131 \begin_layout Subsection
132 print: Print values to console
135 \begin_layout Itemize
136 Syntax: none print(value...
140 \begin_layout Standard
141 Prints specified values to console.
142 Can print any Lua type at least enough to identify the type and instance.
145 \begin_layout Subsection
146 tostringx: Format a value to string
149 \begin_layout Itemize
150 Syntax: string tostringx(value val)
153 \begin_layout Standard
154 Formats value <val> like print would, and returns the result as a string.
157 \begin_layout Subsection
158 exec: Execute lsnes commands
161 \begin_layout Itemize
162 Syntax: none exec(string cmd)
165 \begin_layout Standard
166 Execute lsnes command <cmd>.
169 \begin_layout Subsection
170 utime: Get current time
173 \begin_layout Itemize
174 Syntax: (number,number) utime()
177 \begin_layout Standard
179 First is time since some epoch in seconds, the second is microseconds mod
180 10^6 since that epoch.
183 \begin_layout Subsection
184 emulator_ready: Check if emulator has been fully initialized
187 \begin_layout Itemize
188 Syntax: boolean emulator_ready()
191 \begin_layout Standard
192 Returns true if emulator has finished booting, false if not (on_startup()
193 will be issued later).
196 \begin_layout Subsection
197 set_idle_timeout: Run function after timeout when emulator is idle
200 \begin_layout Itemize
201 Syntax: none set_idle_timeout(number timeout)
204 \begin_layout Standard
205 Set number of microseconds to block idle for.
206 After this timeout has expired, on_idle() will be called once.
209 \begin_layout Subsection
210 set_timer_timeout: Run function after timeout.
213 \begin_layout Itemize
214 Syntax: none set_timer_timeout(number timeout)
217 \begin_layout Standard
218 Set number of microseconds to block timer for.
219 After this timeout has expired, on_timer() will be called once.
222 \begin_layout Subsection
223 bus_address: Look up address in system bus.
226 \begin_layout Itemize
227 Syntax: none bus_address(number bus_addr)
230 \begin_layout Standard
231 Returns virtual address corresponding to specified address on system bus.
234 \begin_layout Subsection
235 loopwrapper: Convert loop into callable function
238 \begin_layout Itemize
239 Syntax: function loopwrapper(function fun, ...)
242 \begin_layout Standard
243 Calls function <fun> with function and specified arguments.
244 The function passed suspends execution until the function returned is called.
245 Handy for linear flow control among multiple invocations of a hook.
249 \begin_layout LyX-Code
250 on_paint = loopwrapper(function(wait)
254 \begin_layout LyX-Code
259 \begin_layout LyX-Code
261 \begin_inset Quotes eld
265 \begin_inset Quotes erd
271 \begin_layout LyX-Code
276 \begin_layout LyX-Code
281 \begin_layout LyX-Code
285 \begin_layout Subsection
286 list_bindings: List keybindings
289 \begin_layout Itemize
290 Syntax: table list_bindings([string cmd])
293 \begin_layout Standard
294 Get table of all keybindings, indexed by keyspec (modifiers|mask/key).
295 If <cmd> is specified, the table is limited to that command.
296 Also searches for controller keys.
299 \begin_layout Subsection
300 get_alias: Get expansion of alias
303 \begin_layout Itemize
304 Syntax: string get_alias(string aname)
307 \begin_layout Standard
308 Get expansion of given alias <aname>.
311 \begin_layout Subsection
312 set_alias: Set expansion of alias
315 \begin_layout Itemize
316 Syntax: none set_alias(string aname, string value)
319 \begin_layout Standard
320 Set expansion of given alias.
323 \begin_layout Subsection
324 create_ibind: Create invese binding
327 \begin_layout Itemize
328 Syntax: INVERSEBIND create_ibind(string name, string cmd)
331 \begin_layout Standard
332 Return object representing inverse binding with specified name <name> and
333 specified command <cmd>.
336 \begin_layout Itemize
337 Note: To create press/release commands, use aliases +foo and -foo .
340 \begin_layout Itemize
341 Note: Keep the returned object around.
344 \begin_layout Subsection
345 create_command: Create a command
348 \begin_layout Itemize
349 Syntax: COMMANDBIND create_commmand(string name, function a)
352 \begin_layout Itemize
353 Syntax: COMMANDBIND create_commmand(string name, function a, function b)
356 \begin_layout Standard
357 Return object representing a command (pair).
360 \begin_layout Itemize
361 If only one function is specied, the command is level-sensitive, <a> is
365 \begin_layout Itemize
366 If <b> is function, the function is edge-sensitive, <a> is positive edge
367 callback and <b> is negative edge callback.
370 \begin_layout Itemize
371 All callbacks get single argument: The parameters passed.
374 \begin_layout Itemize
375 Keep the returned object around.
378 \begin_layout Subsection
379 loadfile: Load Lua script
382 \begin_layout Itemize
383 Syntax: function loadfile(string filename[, string base])
386 \begin_layout Standard
387 Load lua script from <filename>, resolved relative to <base> (if empty,
391 \begin_layout Subsection
392 dofile: Execute Lua script
395 \begin_layout Itemize
396 Syntax: function dofile(string filename[, string base])
399 \begin_layout Standard
400 Execute lua script from <filename>, resolved relative to <base> (if empty,
401 current directory) and return all return values.
404 \begin_layout Subsection
405 open_file: Open a stream
408 \begin_layout Itemize
409 Syntax: FILEREADER open_file(string filename[, string base])
412 \begin_layout Standard
413 Open file <filename>, resolved relative to <base> (if empty, current directory)
417 \begin_layout Subsection
418 FILEREADER(): Read line/bytes from stream
421 \begin_layout Itemize
422 Syntax: string/nil FILEREADER()
425 \begin_layout Itemize
426 Syntax: string/nil FILEREADER(number bytes)
429 \begin_layout Standard
430 Reads next line or <bytes> bytes from specified file handle.
431 On EOF, nil is returned.
434 \begin_layout Itemize
435 Note: The line-oriented variant reads in text mode, so CR at end of line
439 \begin_layout Subsection
440 FILEREADER:lines: Iterator to read all lines
443 \begin_layout Itemize
444 Syntax: for line in <foo>:lines() do ...
448 \begin_layout Standard
449 Iterator for reading all lines of <foo> in a loop.
452 \begin_layout Subsection
453 resolve_filename: Resolve name of file relative to another
456 \begin_layout Itemize
457 Syntax: string resolve_file(string filename, string base)
460 \begin_layout Standard
461 Resolve name of file <filename> relative to <base> and return the result.
464 \begin_layout Standard
465 \begin_inset Newpage pagebreak
471 \begin_layout Section
475 \begin_layout Standard
476 Bitwise logical functions and related.
479 \begin_layout Subsection
480 bit.none/bit.bnot: Bitwise none or NOT function
483 \begin_layout Itemize
484 Syntax: number bit.none(number...)
487 \begin_layout Itemize
488 Syntax: number bit.bnot(number...)
491 \begin_layout Standard
492 48-bit bitwise NOT / NONE function (set bits that are set in none of the
496 \begin_layout Subsection
497 bit.any/bit.bor: Bitwise any or OR function
500 \begin_layout Itemize
501 Syntax: number bit.any(number...)
504 \begin_layout Itemize
505 Syntax: number bit.bor(number...)
508 \begin_layout Standard
509 48-bit bitwise OR / ANY function (set bits that are set in any of the arguments).
512 \begin_layout Subsection
513 bit.all/bit.band: Bitwise all or AND function
516 \begin_layout Itemize
517 Syntax: number bit.all(number...)
520 \begin_layout Itemize
521 Syntax: number bit.band(number...)
524 \begin_layout Standard
525 48-bit bitwise AND / ALL function (set bits that are set in all of the arguments
529 \begin_layout Subsection
530 bit.parity/bit.bxor: Bitwise parity or XOR function
533 \begin_layout Itemize
534 Syntax: number bit.parity(number...)
537 \begin_layout Itemize
538 Syntax: number bit.bxor(number...)
541 \begin_layout Standard
542 48-bit bitwise XOR / PARITY function (set bits that are set in odd number
546 \begin_layout Subsection
547 bit.lrotate: Rotate a number left
550 \begin_layout Itemize
551 Syntax: number bit.lrotate(number base[, number amount[, number bits]])
554 \begin_layout Standard
555 Rotate <bits>-bit (max 48, default 48) number <base> left by <amount> (default
559 \begin_layout Subsection
560 bit.rrotate: Rotate a number right
563 \begin_layout Itemize
564 Syntax: number bit.rrotate(number base[, number amount[, number bits]])
567 \begin_layout Standard
568 Rotate <bits>-bit (max 48, default 48) number <base> right by <amount> (default
572 \begin_layout Subsection
573 bit.lshift: Shift a number left
576 \begin_layout Itemize
577 Syntax: number bit.lshift(number base[, number amount[, number bits]])
580 \begin_layout Standard
581 Shift <bits>-bit (max 48, default 48) number <base> left by <amount> (default
583 The new bits are filled with zeroes.
586 \begin_layout Subsection
587 bit.lrshift: Shift a number right (logical)
590 \begin_layout Itemize
591 Syntax: number bit.lrshift(number base[, number amount[, number bits]])
594 \begin_layout Standard
595 Shift <bits>-bit (max 48, default 48) number <base> logically right by <amount>
597 The new bits are filled with zeroes.
600 \begin_layout Subsection
601 bit.arshift: Shift a number right (arithmetic)
604 \begin_layout Itemize
605 Syntax: number bit.arshift(number base[, number amount[, number bits]])
608 \begin_layout Standard
609 Shift <bits>-bit (max 48, default 48) number <base> logically right by <amount>
611 The new bits are shifted in with copy of the high bit.
614 \begin_layout Subsection
615 bit.extract: Extract/shuffle bits from number
618 \begin_layout Itemize
619 Syntax: number bit.extract(number base[, number bit0[, number bit1,...]])
622 \begin_layout Standard
623 Returns number that has bit0-th bit as bit 0, bit1-th bit as 1 and so on.
626 \begin_layout Itemize
627 Note: Bit numbers up to 51 should work reliably (then things start falling
628 apart due to double precision issues).
631 \begin_layout Itemize
632 Note: There are two special bit positions, true and false, standing for
633 always set bit and always clear bit.
636 \begin_layout Subsection
637 bit.value: Construct number with specified bits set
640 \begin_layout Itemize
641 Syntax: number bit.value([number bit1[, number bit2,...]])
644 \begin_layout Standard
645 Returns bitwise OR of 1 left shifted by <bit1> places, 1 left shifted by
646 <bit2> places and so on.
647 As special value, nil argument is no-op.
650 \begin_layout Subsection
651 bit.test_any: Test if any bit is set
654 \begin_layout Itemize
655 Syntax: boolean bit.test_any(number a, number b)
658 \begin_layout Standard
659 Returns true if bitwise and of <a> and <b> is nonzero, otherwise false.
662 \begin_layout Subsection
663 bit.test_all: Test if all bits are set
666 \begin_layout Itemize
667 Syntax: boolean bit.test_all(number a, number b)
670 \begin_layout Standard
671 Returns true if bitwise and of <a> and <b> equals <b>, otherwise false.
674 \begin_layout Subsection
675 bit.popcount: Population count
678 \begin_layout Itemize
679 Syntax: number bit.popcount(number a)
682 \begin_layout Standard
683 Returns number of set bits in <a>.
686 \begin_layout Subsection
687 bit.clshift: Chained left shift
690 \begin_layout Itemize
691 Syntax: (number, number) bit.clshift(number a, number b, [number amount,[number
695 \begin_layout Standard
696 Does chained left shift on <a>, <b> by <amount> positions (default 1), assuming
697 numbers to be of specified number of bits <bits> (default 48).
700 \begin_layout Subsection
701 bit.crshift: Chained right shift
704 \begin_layout Itemize
705 Syntax: (number, number) bit.crshift(number a, number b, [number amount,[number
709 \begin_layout Standard
710 Does chained right shift on <a>, <b> by <amount> positions (default 1),
711 assuming numbers to be of specified number of bits <bits> (default 48).
714 \begin_layout Subsection
715 bit.flagdecode: Decode bitfield into flags
718 \begin_layout Itemize
719 Syntax: string bit.flagdecode(number a, number bits, [string on, [string
723 \begin_layout Standard
724 Return string of length bits where ith character is ith character of on
725 if bit i is on, otherwise ith character of off.
726 Out of range reads give last character.
729 \begin_layout Itemize
730 Note: <on> defaults to '*' if empty.
733 \begin_layout Itemize
734 Note: <off> defaults to '-' if empty.
737 \begin_layout Subsection
738 bit.rflagdecode: Decode bitfield into flags
741 \begin_layout Itemize
742 Syntax: string bit.rflagdecode(number a, number bits, [string on, [string
746 \begin_layout Standard
747 Like bit.flagdecode, but outputs the string in the opposite order (most significa
751 \begin_layout Standard
752 \begin_inset Newpage pagebreak
758 \begin_layout Section
762 \begin_layout Itemize
763 Functions that draw to screen can only only be called in on_paint and on_video
764 callbacks or if non-default render queue has been set.
767 \begin_layout Itemize
769 Bits 0-7 are the blue component, bits 8-15 are the green component, bits
770 16-23 are the red component, bits 24-31 are alpha component (0 is fully
771 opaque, 255 is almost transparent).
772 -1 is the fully transparent color.
773 Alternatively, colors can be given as strings naming the color.
776 \begin_layout Itemize
777 Alpha values greater than 127 do work properly.
780 \begin_layout Itemize
781 Origin of coordinates is at top left corner of game display area.
782 Left and top gaps correspond to negative coordinates.
785 \begin_layout Itemize
786 The following color names are known: aliceblue antiquewhite antiquewhite1
787 antiquewhite2 antiquewhite3 antiquewhite4 aqua aquamarine aquamarine1 aquamarin
788 e2 aquamarine3 aquamarine4 azure azure1 azure2 azure3 azure4 beige bisque
789 bisque1 bisque2 bisque3 bisque4 black blanchedalmond blue blue1 blue2 blue3
790 blue4 blueviolet brown brown1 brown2 brown3 brown4 burlywood burlywood1
791 burlywood2 burlywood3 burlywood4 cadet cadetblue cadetblue1 cadetblue2
792 cadetblue3 cadetblue4 chartreuse chartreuse1 chartreuse2 chartreuse3 chartreuse
793 4 chocolate chocolate1 chocolate2 chocolate3 chocolate4 coral coral1 coral2
794 coral3 coral4 cornflowerblue cornsilk cornsilk1 cornsilk2 cornsilk3 cornsilk4
795 crimson cyan cyan1 cyan2 cyan3 cyan4 darkblue darkcyan darkgoldenrod darkgolden
796 rod1 darkgoldenrod2 darkgoldenrod3 darkgoldenrod4 darkgray darkgreen darkgrey
797 darkkhaki darkmagenta darkolivegreen darkolivegreen1 darkolivegreen2 darkoliveg
798 reen3 darkolivegreen4 darkorange darkorange1 darkorange2 darkorange3 darkorange4
799 darkorchid darkorchid1 darkorchid2 darkorchid3 darkorchid4 darkred darksalmon
800 darkseagreen darkseagreen1 darkseagreen2 darkseagreen3 darkseagreen4 darkslateb
801 lue darkslategray darkslategray1 darkslategray2 darkslategray3 darkslategray4
802 darkslategrey darkturquoise darkviolet deeppink deeppink1 deeppink2 deeppink3
803 deeppink4 deepskyblue deepskyblue1 deepskyblue2 deepskyblue3 deepskyblue4
804 dimgray dimgrey dodgerblue dodgerblue1 dodgerblue2 dodgerblue3 dodgerblue4
805 firebrick firebrick1 firebrick2 firebrick3 firebrick4 floralwhite forestgreen
806 fractal fuchsia gainsboro ghostwhite gold gold1 gold2 gold3 gold4 goldenrod
807 goldenrod1 goldenrod2 goldenrod3 goldenrod4 gray gray0 gray1 gray10 gray100
808 gray11 gray12 gray13 gray14 gray15 gray16 gray17 gray18 gray19 gray2 gray20
809 gray21 gray22 gray23 gray24 gray25 gray26 gray27 gray28 gray29 gray3 gray30
810 gray31 gray32 gray33 gray34 gray35 gray36 gray37 gray38 gray39 gray4 gray40
811 gray41 gray42 gray43 gray44 gray45 gray46 gray47 gray48 gray49 gray5 gray50
812 gray51 gray52 gray53 gray54 gray55 gray56 gray57 gray58 gray59 gray6 gray60
813 gray61 gray62 gray63 gray64 gray65 gray66 gray67 gray68 gray69 gray7 gray70
814 gray71 gray72 gray73 gray74 gray75 gray76 gray77 gray78 gray79 gray8 gray80
815 gray81 gray82 gray83 gray84 gray85 gray86 gray87 gray88 gray89 gray9 gray90
816 gray91 gray92 gray93 gray94 gray95 gray96 gray97 gray98 gray99 green green1
817 green2 green3 green4 greenyellow grey grey0 grey1 grey10 grey100 grey11
818 grey12 grey13 grey14 grey15 grey16 grey17 grey18 grey19 grey2 grey20 grey21
819 grey22 grey23 grey24 grey25 grey26 grey27 grey28 grey29 grey3 grey30 grey31
820 grey32 grey33 grey34 grey35 grey36 grey37 grey38 grey39 grey4 grey40 grey41
821 grey42 grey43 grey44 grey45 grey46 grey47 grey48 grey49 grey5 grey50 grey51
822 grey52 grey53 grey54 grey55 grey56 grey57 grey58 grey59 grey6 grey60 grey61
823 grey62 grey63 grey64 grey65 grey66 grey67 grey68 grey69 grey7 grey70 grey71
824 grey72 grey73 grey74 grey75 grey76 grey77 grey78 grey79 grey8 grey80 grey81
825 grey82 grey83 grey84 grey85 grey86 grey87 grey88 grey89 grey9 grey90 grey91
826 grey92 grey93 grey94 grey95 grey96 grey97 grey98 grey99 honeydew honeydew1
827 honeydew2 honeydew3 honeydew4 hotpink hotpink1 hotpink2 hotpink3 hotpink4
828 indianred indianred1 indianred2 indianred3 indianred4 indigo ivory ivory1
829 ivory2 ivory3 ivory4 khaki khaki1 khaki2 khaki3 khaki4 lavender lavenderblush
830 lavenderblush1 lavenderblush2 lavenderblush3 lavenderblush4 lawngreen lemonchif
831 fon lemonchiffon1 lemonchiffon2 lemonchiffon3 lemonchiffon4 lightblue lightblue1
832 lightblue2 lightblue3 lightblue4 lightcoral lightcyan lightcyan1 lightcyan2
833 lightcyan3 lightcyan4 lightgoldenrod lightgoldenrod1 lightgoldenrod2 lightgolde
834 nrod3 lightgoldenrod4 lightgoldenrodyellow lightgray lightgreen lightgrey
835 lightpink lightpink1 lightpink2 lightpink3 lightpink4 lightsalmon lightsalmon1
836 lightsalmon2 lightsalmon3 lightsalmon4 lightseagreen lightskyblue lightskyblue1
837 lightskyblue2 lightskyblue3 lightskyblue4 lightslateblue lightslategray
838 lightslategrey lightsteelblue lightsteelblue1 lightsteelblue2 lightsteelblue3
839 lightsteelblue4 lightyellow lightyellow1 lightyellow2 lightyellow3 lightyellow4
840 lime limegreen linen magenta magenta1 magenta2 magenta3 magenta4 maroon
841 maroon1 maroon2 maroon3 maroon4 mediumaquamarine mediumblue mediumforestgreen
842 mediumgoldenrod mediumorchid mediumorchid1 mediumorchid2 mediumorchid3
843 mediumorchid4 mediumpurple mediumpurple1 mediumpurple2 mediumpurple3 mediumpurp
844 le4 mediumseagreen mediumslateblue mediumspringgreen mediumturquoise mediumviole
845 tred midnightblue mintcream mistyrose mistyrose1 mistyrose2 mistyrose3 mistyrose
846 4 moccasin navajowhite navajowhite1 navajowhite2 navajowhite3 navajowhite4
847 navy navyblue oldlace olive olivedrab olivedrab1 olivedrab2 olivedrab3
848 olivedrab4 orange orange1 orange2 orange3 orange4 orangered orangered1
849 orangered2 orangered3 orangered4 orchid orchid1 orchid2 orchid3 orchid4
850 palegoldenrod palegreen palegreen1 palegreen2 palegreen3 palegreen4 paleturquoi
851 se paleturquoise1 paleturquoise2 paleturquoise3 paleturquoise4 palevioletred
852 palevioletred1 palevioletred2 palevioletred3 palevioletred4 papayawhip
853 peachpuff peachpuff1 peachpuff2 peachpuff3 peachpuff4 peru pink pink1 pink2
854 pink3 pink4 plum plum1 plum2 plum3 plum4 powderblue purple purple1 purple2
855 purple3 purple4 red red1 red2 red3 red4 rosybrown rosybrown1 rosybrown2
856 rosybrown3 rosybrown4 royalblue royalblue1 royalblue2 royalblue3 royalblue4
857 saddlebrown salmon salmon1 salmon2 salmon3 salmon4 sandybrown seagreen
858 seagreen1 seagreen2 seagreen3 seagreen4 seashell seashell1 seashell2 seashell3
859 seashell4 sienna sienna1 sienna2 sienna3 sienna4 silver skyblue skyblue1
860 skyblue2 skyblue3 skyblue4 slateblue slateblue1 slateblue2 slateblue3 slateblue
861 4 slategray slategray1 slategray2 slategray3 slategray4 slategrey snow snow1
862 snow2 snow3 snow4 springgreen springgreen1 springgreen2 springgreen3 springgree
863 n4 steelblue steelblue1 steelblue2 steelblue3 steelblue4 tan tan1 tan2 tan3
864 tan4 teal thistle thistle1 thistle2 thistle3 thistle4 tomato tomato1 tomato2
865 tomato3 tomato4 transparent turquoise turquoise1 turquoise2 turquoise3
866 turquoise4 violet violetred violetred1 violetred2 violetred3 violetred4
867 wheat wheat1 wheat2 wheat3 wheat4 white whitesmoke yellow yellow1 yellow2
868 yellow3 yellow4 yellowgreen hsl-{r,ry,o,y,yg,g,gc,c,cb,b,bm,m,mr}{0,1,2,3,4,5,6
869 ,7,8}{0,1,2,3,4,5,6,7,8}.
872 \begin_layout Itemize
873 The following modifiers can be applied: opaque10, opaque20, opaque25, opaque30,
874 opaque40, opaque50, opaque60, opaque70, opaque75, opaque80, opaque90, opaque,
875 hue{+,-}{1-23}, {saturation,lightness}{+,-}{1-16}.
878 \begin_layout Itemize
879 HSL base color names: r => Red, ry => Red-Yellow (also o).
880 y => Yellow, yg => Yellow-Green, g => Green, gc => Green-Cyan, c => Cyan,
881 cb => Cyan-Blue, b => Blue, bm => Blue-Magenta, m => Magenta, mr => Magenta
885 \begin_layout Itemize
886 HSL colors use 8-step scales for saturation and lightness.
889 \begin_layout Itemize
890 Modifiers have opaqueness on percent scale (0 is transparent, 100 is fully
894 \begin_layout Itemize
895 Modifiers have Hue on 24-step scale (4 steps between R->Y->G->C->B->M->R).
898 \begin_layout Itemize
899 Modifiers have Saturation/Lightness on 16 step scale.
902 \begin_layout Subsection
903 gui.resolution: Get current resolution
906 \begin_layout Itemize
907 Syntax: (number, number) gui.resolution()
910 \begin_layout Standard
911 Returns 2-tuple (hresolution, vresolution).
914 \begin_layout Subsection
915 gui.left_gap/gui.right_gap/gui.top_gap/gui.bottom_gap: Set edge gaps
918 \begin_layout Itemize
919 Syntax: number gui.left_gap(number gap)
922 \begin_layout Itemize
923 Syntax: number gui.right_gap(number gap)
926 \begin_layout Itemize
927 Syntax: number gui.top_gap(number gap)
930 \begin_layout Itemize
931 Syntax: number gui.bottom_gap(number gap)
934 \begin_layout Standard
935 Set the specified edge gap to specified value <gap> (max gap is 8191).
936 If successful, old gap is returned.
939 \begin_layout Subsection
940 gui.delta_left_gap/gui.delta_right_gap/gui.delta_top_gap/gui.delta_bottom_gap:
944 \begin_layout Itemize
945 Syntax: number gui.delta_left_gap(number dgap)
948 \begin_layout Itemize
949 Syntax: number gui.delta_right_gap(number dgap)
952 \begin_layout Itemize
953 Syntax: number gui.delta_top_gap(number dgap)
956 \begin_layout Itemize
957 Syntax: number gui.delta_bottom_gap(number dgap)
960 \begin_layout Standard
961 Increase the specified edge gap by specified value <dgap> (max gap is 8191)
962 and return the old gap (returns nothing on error).
965 \begin_layout Subsection
966 gui.text/gui.textH/gui.textV,gui.textHV: Draw text
969 \begin_layout Itemize
970 Syntax: none gui.text(number x, number y, string text[, number fgc[, number
974 \begin_layout Itemize
975 Syntax: none gui.textH(number x, number y, string text[, number fgc[, number
979 \begin_layout Itemize
980 Syntax: none gui.textV(number x, number y, string text[, number fgc[, number
984 \begin_layout Itemize
985 Syntax: none gui.textHV(number x, number y, string text[, number fgc[, number
989 \begin_layout Standard
990 Draw specified text on the GUI (each character cell is 8 or 16 wide and
995 \begin_layout Itemize
996 x: X-coordinate to start the drawing from (and x-coordinate at begining
1000 \begin_layout Itemize
1001 y: Y-coordinate to start the drawing from.
1004 \begin_layout Itemize
1005 text: The text to draw.
1008 \begin_layout Itemize
1009 fgc: Text color (default is 0xFFFFFF (white))
1012 \begin_layout Itemize
1013 bgc: Background color (default is -1 (transparent))
1016 \begin_layout Standard
1017 Note: The H variants draw at double width and V variants draw at double
1021 \begin_layout Subsection
1022 gui.rectangle: Draw a rectangle
1025 \begin_layout Itemize
1026 Syntax: none gui.rectangle(number x, number y, number width, number height[,
1027 number thickness[, number outline[, number fill]]])
1030 \begin_layout Standard
1031 Draw rectangle on the GUI.
1035 \begin_layout Itemize
1036 x: X-coordinate of left edge.
1039 \begin_layout Itemize
1040 y: Y-coordinate of upper edge.
1043 \begin_layout Itemize
1044 width: Width of rectangle.
1047 \begin_layout Itemize
1048 height: Height of rectangle.
1051 \begin_layout Itemize
1052 thickness: Thickness of outline (default is 1).
1055 \begin_layout Itemize
1056 outline: Color of outline (default is 0xFFFFFF (white))
1059 \begin_layout Itemize
1060 fill: Color of fill (default is -1 (transparent))
1063 \begin_layout Subsection
1064 gui.box: Draw a 3D-effect box
1067 \begin_layout Itemize
1068 Syntax: none gui.box(number x, number y, number width, number height[, number
1069 thickness[, number outline1[,number outline2[, number fill]]]])
1072 \begin_layout Standard
1073 Draw rectangle with 3D effect on the GUI.
1077 \begin_layout Itemize
1078 x: X-coordinate of left edge.
1081 \begin_layout Itemize
1082 y: Y-coordinate of upper edge.
1085 \begin_layout Itemize
1086 width: Width of rectangle.
1089 \begin_layout Itemize
1090 height: Height of rectangle.
1093 \begin_layout Itemize
1094 thickness: Thickness of outline (default is 1).
1097 \begin_layout Itemize
1098 outline1: First color of outline (default is 0xFFFFFF (white))
1101 \begin_layout Itemize
1102 outline2: First color of outline (default is 0x808080 (dark gray))
1105 \begin_layout Itemize
1106 fill: Color of fill (default is 0xC0C0C0 (light grayy))
1109 \begin_layout Subsection
1110 gui.pixel: Draw a single pixel
1113 \begin_layout Itemize
1114 Syntax: none gui.pixel(number x, number y[, number color])
1117 \begin_layout Standard
1118 Draw one pixel on the GUI.
1122 \begin_layout Itemize
1123 x: X-coordinate of the pixel
1126 \begin_layout Itemize
1127 y: Y-coordinate of the pixel
1130 \begin_layout Itemize
1131 color: Color of the pixel (default is 0xFFFFFF (white))
1134 \begin_layout Subsection
1135 gui.crosshair: Draw a crosshair
1138 \begin_layout Itemize
1139 Syntax: none gui.crosshair(number x, number y[, number length[, number color]])
1142 \begin_layout Standard
1147 \begin_layout Itemize
1148 x: X-coordinate of the crosshair
1151 \begin_layout Itemize
1152 y: Y-coordinate of the crosshair
1155 \begin_layout Itemize
1156 length: Length of the crosshair lines (default 10).
1159 \begin_layout Itemize
1160 color: Color of the crosshair (default is 0xFFFFFF (white))
1163 \begin_layout Subsection
1164 gui.line: Draw a line
1167 \begin_layout Itemize
1168 Syntax: none gui.line(number x1, number y1, number x2, number y2[, number
1172 \begin_layout Standard
1177 \begin_layout Itemize
1178 x1: X-coordinate of one end.
1181 \begin_layout Itemize
1182 y1: Y-coordinate of one end.
1185 \begin_layout Itemize
1186 x2: X-coordinate of the other end.
1189 \begin_layout Itemize
1190 y2: Y-coordinate of the other end.
1193 \begin_layout Itemize
1194 color: Color of the line (default is 0xFFFFFF (white)).
1197 \begin_layout Subsection
1198 gui.circle: Draw a (filled) circle
1201 \begin_layout Itemize
1202 Syntax: none gui.circle(number x, number y, number r[, number thick[, number
1203 border[, number fil]]])
1206 \begin_layout Standard
1211 \begin_layout Itemize
1212 x: X-coordinate of the center
1215 \begin_layout Itemize
1216 y: Y-coordinate of the center
1219 \begin_layout Itemize
1220 r: The radius of the circle
1223 \begin_layout Itemize
1224 thick: Border thickness
1227 \begin_layout Itemize
1228 border: Border color (default is 0xFFFFFF (white))
1231 \begin_layout Itemize
1232 fill: Fill color (default is -1 (transparent)).
1235 \begin_layout Subsection
1236 gui.bitmap_draw/(D)BITMAP:draw: Draw a bitmap
1239 \begin_layout Itemize
1240 Syntax: none gui.bitmap_draw(number x, number y, BITMAP bitmap, PALETTE palette)
1243 \begin_layout Itemize
1244 Syntax: none gui.bitmap_draw(number x, number y, DBITMAP bitmap)
1247 \begin_layout Itemize
1248 Syntax: none BITMAP:draw(number x, number y, PALETTE palette)
1251 \begin_layout Itemize
1252 Syntax: none DBITMAP:draw(number x, number y)
1255 \begin_layout Standard
1256 Draw a bitmap <bitmap> (or object) on screen with specified palette <palette>
1257 (if bitmap is paletted) .
1261 \begin_layout Itemize
1262 x: X-coordinate of left edge.
1265 \begin_layout Itemize
1266 y: Y-coordinate of top edge.
1269 \begin_layout Itemize
1270 bitmap: The bitmap to draw
1273 \begin_layout Itemize
1274 palette: The palette to draw the bitmap using.
1277 \begin_layout Subsection
1278 gui.palette_new: Create a new palette
1281 \begin_layout Itemize
1282 Syntax: PALETTE gui.palette_new()
1285 \begin_layout Standard
1286 Returns a new palette (initially all transparent).
1290 \begin_layout Subsection
1291 gui.bitmap_new: Create a new bitmap
1294 \begin_layout Itemize
1295 Syntax: BITMAP/DBITMAP gui.bitmap_new(number w, number h, boolean direct[,
1299 \begin_layout Standard
1300 Returns a new bitmap/dbitmap.
1303 \begin_layout Standard
1307 \begin_layout Itemize
1308 w: The width of new bitmap
1311 \begin_layout Itemize
1312 h: The height of new bitmap
1315 \begin_layout Itemize
1316 direct: If true, the returned bitmap is dbitmap, otherwise bitmap.
1319 \begin_layout Itemize
1320 icolor: Initital fill color (defaults to 0 on BITMAP, -1 on DBITMAP)
1323 \begin_layout Subsection
1324 gui.bitmap_load/gui.bitmap_load_str: Load a bitmap from file or string
1327 \begin_layout Itemize
1328 Syntax: DBITMAP/(BITMAP, PALETTE) gui.bitmap_load(string file[, string base])
1331 \begin_layout Itemize
1332 Syntax: DBITMAP/(BITMAP, PALETTE) gui.bitmap_load_str(string content)
1335 \begin_layout Standard
1336 Reads file <file> (resolved relative to <base>) or string <content> and
1337 returns loaded bitmap/dbitmap (if bitmap, the second return value is palette
1341 \begin_layout Subsection
1342 gui.bitmap_load_png/gui.bitmap_load_png_str: Load a bitmap from PNG
1345 \begin_layout Itemize
1346 Syntax: DBITMAP/(BITMAP, PALETTE) gui.bitmap_load_png(string file[, string
1350 \begin_layout Itemize
1351 Syntax: DBITMAP/(BITMAP, PALETTE) gui.bitmap_load_png_str(string content)
1354 \begin_layout Standard
1355 Load a bitmap from PNG file <file> (resolved relative to <base>) or BASE64
1356 encoded content <content>.
1359 \begin_layout Itemize
1360 If the PNG is of color type 3 (PALETTE), returns two values.
1361 First is BITMAP containing the image data from the PNG and second is PALETTE
1362 containg the palette data from the PNG.
1365 \begin_layout Itemize
1366 For color types 0 (GRAY), 2 (RGB), 4 (GRAY_ALPHA) and 6 (RGBA), returns
1367 one DBITMAP containg the image data loaded from the PNG.
1370 \begin_layout Subsection
1371 gui.bitmap_load_pal/gui.bitmap_load_pal_str: Load a palette
1374 \begin_layout Itemize
1375 Syntax: PALETTE gui.bitmap_load_pal(string file[, string base])
1378 \begin_layout Itemize
1379 Syntax: PALETTE gui.bitmap_load_pal_str(string content)
1382 \begin_layout Standard
1383 Load a palette from file <file>(resolved relative to <base>) or string <content>.
1386 \begin_layout Itemize
1387 The kinds of lines supported:
1391 \begin_layout Itemize
1392 Blank or just whitespace: Ignored
1395 \begin_layout Itemize
1396 First non-whitespace is '#': Ignored
1399 \begin_layout Itemize
1400 <r> <g> <b>: Fully opaque color with specified RGB values (0-255)
1403 \begin_layout Itemize
1404 <r> <g> <b> <a>: Color with specified RGB values (0-255) and specified alpha
1405 (0-256, 0 being fully transparent and 256 fully opaque).
1408 \begin_layout Itemize
1409 transparent: Fully transparent color
1413 \begin_layout Subsection
1414 gui.palette_set/PALETTE:set: Set palette entry
1417 \begin_layout Itemize
1418 Syntax: none gui.palette_set(PALETTE palette, number index, number color)
1421 \begin_layout Itemize
1422 Syntax: none PALETTE:set(number index, number color)
1425 \begin_layout Standard
1426 Sets color in palette.
1430 \begin_layout Itemize
1431 palette: The palette to manipulate
1434 \begin_layout Itemize
1435 index: Index of color (0-65535).
1438 \begin_layout Itemize
1439 color: The color value.
1442 \begin_layout Subsection
1443 gui.bitmap_pset/(D)BITMAP:pset: Set pixel in bitmap
1446 \begin_layout Itemize
1447 Syntax: none gui.bitmap_pset(BITMAP/DBITMAP bitmap, number x, number y, number
1451 \begin_layout Itemize
1452 Syntax: none BITMAP:pset(number x, number y, number color)
1455 \begin_layout Itemize
1456 Syntax: none DBITMAP:pset(number x, number y, number color)
1459 \begin_layout Standard
1460 Sets specified pixel in bitmap.
1464 \begin_layout Itemize
1465 bitmap: The bitmap to manipulate
1468 \begin_layout Itemize
1469 x: The x-coordinate of the pixel.
1472 \begin_layout Itemize
1473 y: The y-coordinate of the pixel.
1476 \begin_layout Itemize
1477 color: If bitmap is a bitmap, color index (0-65535).
1478 Otherwise color value.
1481 \begin_layout Subsection
1482 gui.bitmap_pget/(D)BITMAP:pget: Get pixel in bitmap
1485 \begin_layout Itemize
1486 Syntax: number gui.bitmap_pget(BITMAP/DBITMAP bitmap, number x, number y)
1489 \begin_layout Itemize
1490 Syntax: number BITMAP:pget(number x, number y)
1493 \begin_layout Itemize
1494 Syntax: number DBITMAP:pget(number x, number y)
1497 \begin_layout Standard
1498 Gets specified pixel in bitmap.
1502 \begin_layout Itemize
1503 bitmap: The bitmap to query
1506 \begin_layout Itemize
1507 x: The x-coordinate of the pixel.
1510 \begin_layout Itemize
1511 y: The y-coordinate of the pixel.
1514 \begin_layout Standard
1515 The bitmap color (color index if paletted, otherwise color value).
1518 \begin_layout Subsection
1519 gui.bitmap_size/(D)BITMAP:size: Get size of bitmap
1522 \begin_layout Itemize
1523 Syntax: (number, number) gui.bitmap_size(BITMAP/DBITMAP bitmap)
1526 \begin_layout Itemize
1527 Syntax: (number, number) BITMAP:size()
1530 \begin_layout Itemize
1531 Syntax: (number, number) DBITMAP:size()
1534 \begin_layout Standard
1535 Get size of bitmap <bitmap>.
1536 The first return is the width, the second is the height.
1539 \begin_layout Itemize
1540 Note: Can be used anywhere.
1543 \begin_layout Subsection
1544 gui.bitmap_blit/(D)BITMAP:blit: Blit a bitmap into another
1547 \begin_layout Itemize
1548 Syntax: none gui.bitmap_blit(BITMAP dest, number dx, number dy, BITMAP src,
1549 number sx, number sy, number w, number h[, number ck])
1552 \begin_layout Itemize
1553 Syntax: none gui.bitmap_blit(DBITMAP dest, number dx, number dy, DBITMAP
1554 src, number sx, number sy, number w, number h[, number ck])
1557 \begin_layout Itemize
1558 Syntax: none gui.bitmap_blit(DBITMAP dest, number dx, number dy, BITMAP src,
1559 PALETTE pal, number sx, number sy, number w, number h[, number ck])
1562 \begin_layout Itemize
1563 Syntax: none BITMAP::blit(number dx, number dy, BITMAP src, number sx, number
1564 sy, number w, number h[, number ck])
1567 \begin_layout Itemize
1568 Syntax: none DBITMAP::blit(number dx, number dy, DBITMAP src, number sx,
1569 number sy, number w, number h[, number ck])
1572 \begin_layout Itemize
1573 Syntax: none DBITMAP:blit(number dx, number dy, BITMAP src, PALETTE pal,
1574 number sx, number sy, number w, number h[, number ck])
1577 \begin_layout Standard
1578 Blit a part of bitmap to another (current object if any is destination).
1582 \begin_layout Itemize
1583 dest: Destination to blit to.
1586 \begin_layout Itemize
1587 dx: left edge of target
1590 \begin_layout Itemize
1591 dy: Top edge of target
1594 \begin_layout Itemize
1595 src: The source to blit from.
1598 \begin_layout Itemize
1599 pal: The palette to use in blit.
1602 \begin_layout Itemize
1603 sx: left edge of source
1606 \begin_layout Itemize
1607 sy: Top edge of source
1610 \begin_layout Itemize
1614 \begin_layout Itemize
1615 h: Height of region.
1618 \begin_layout Itemize
1620 Pixels of this color are not blitted.
1624 \begin_layout Itemize
1625 If soruce bitmap is bitmap, this is color index of colorkey.
1626 Values outside range 0-65535 cause no key to be used as colorkey.
1629 \begin_layout Itemize
1630 If source bitmap is dbitmap, this is the color value of colorkey.
1633 \begin_layout Itemize
1634 May be absent or nil for no colorkey blit.
1638 \begin_layout Subsection
1639 gui.repaint: Arrange a repaint
1642 \begin_layout Itemize
1643 Syntax: none gui.repaint()
1646 \begin_layout Standard
1647 Request on_repaint() to happen as soon as possible.
1650 \begin_layout Subsection
1651 gui.synchronous_repaint/RENDERQUEUE:synchronous_repaint: Paint screen now
1654 \begin_layout Itemize
1655 Syntax: none gui.synchronous_repaint(RENDERQUEUE queue)
1658 \begin_layout Itemize
1659 Syntax: none RENDERQUEUE::synchronous_repaint()
1662 \begin_layout Standard
1663 Paints specified render queue on screen right there and then.
1666 \begin_layout Subsection
1667 gui.subframe_update: Enable/Disable subframe updates
1670 \begin_layout Itemize
1671 Syntax: none gui.subframe_update(boolean on)
1674 \begin_layout Standard
1675 Request subframe updates (calling on_paint() on subframes) to happen (<on>=true)
1676 or not happen (<on>=false).
1679 \begin_layout Subsection
1680 gui.screenshot: Write a screenshot
1683 \begin_layout Itemize
1684 Syntax: none gui.screenshot(string filename)
1687 \begin_layout Standard
1688 Write PNG screenshot of the current frame (no drawings) to specified file
1692 \begin_layout Subsection
1693 gui.screenshot_bitmap: Write a screenshot to bitmap
1696 \begin_layout Itemize
1697 Syntax: DBITMAP gui.screenshot_bitmap()
1700 \begin_layout Standard
1701 Write PNG screenshot of the current frame (no drawings) to dbitmap and return
1705 \begin_layout Subsection
1706 gui.color: Compose a color.
1709 \begin_layout Itemize
1710 Syntax: number gui.color(number r, number g, number b[, number a])
1713 \begin_layout Itemize
1714 Syntax: number gui.color(string c)
1717 \begin_layout Standard
1718 Returns color (in notation Lua scripts use) corresponding to color (<r>,<g>,<b>)
1719 , each component in scale 0-255.
1720 If <a> is specified, that is alpha (0 is fully transparent, 256(sic) is
1722 The default alpha is 256.
1725 \begin_layout Standard
1726 The form taking a string returns color corresponding color name.
1729 \begin_layout Subsection
1730 gui.status: Set status variable
1733 \begin_layout Itemize
1734 Syntax: none gui.status(string name, string value)
1737 \begin_layout Standard
1739 \begin_inset Quotes eld
1743 \begin_inset Quotes erd
1746 to <value> in status area.
1749 \begin_layout Subsection
1750 gui.rainbow: Rainbow color calculation
1753 \begin_layout Itemize
1754 Syntax: number gui.rainbow(number step, number steps[, number color])
1757 \begin_layout Standard
1758 Perform hue rotation of color <color> (default bright red), by <step> steps.
1759 The number of steps per full rotation is given by absolute value of <steps>.
1762 \begin_layout Standard
1763 If <step> is negative, the rotation will be counterclockwise.
1766 \begin_layout Subsection
1767 gui.renderq_new: Create a render queue
1770 \begin_layout Itemize
1771 Syntax: RENDERQUEUE gui.renderq_new(number width, number height)
1774 \begin_layout Standard
1775 Create render queue with specified reported size and return it.
1778 \begin_layout Subsection
1779 gui.renderq_clear/RENDERQUEUE:clear: Clear a render queue
1782 \begin_layout Itemize
1783 Syntax: none gui.renderq_clear(RENDERQUEUE queue)
1786 \begin_layout Itemize
1787 Syntax: none RENDERQUEUE:clear()
1790 \begin_layout Standard
1791 Clear specified render queue.
1794 \begin_layout Subsection
1795 gui.renderq_set/RENDERQUEUE:set: Change active render queue
1798 \begin_layout Itemize
1799 Syntax: none gui.renderq_set(RENDERQUEUE queue)
1802 \begin_layout Itemize
1803 Syntax: none RENDERQUEUE:set()
1806 \begin_layout Standard
1807 Switch to specified render queue.
1808 Use nil as queue to switch to default queue.
1811 \begin_layout Itemize
1812 Note: When switched to another queue, all drawing functions work and draw
1813 there, even outside on_video/on_paint.
1816 \begin_layout Subsection
1817 gui.renderq_run/RENDERQUEUE:run: Run render queue
1820 \begin_layout Itemize
1821 Syntax: none gui.renderq_run(RENDERQUEUE queue)
1824 \begin_layout Itemize
1825 Syntax: none RENDERQUEUE:run()
1828 \begin_layout Standard
1829 Run specified render queue, copying the objects to current render queue.
1833 \begin_layout Itemize
1834 Warning: Don't try to run the current render queue.
1837 \begin_layout Subsection
1838 RENDERQUEUE:render: Render a queue to DBITMAP
1841 \begin_layout Itemize
1842 Syntax: DBITMAP RENDERQUEUE:render()
1845 \begin_layout Standard
1846 Renders the specified render queue to a bitmap, the base bitmap size (modified
1847 by gaps) being the nominal screen size for render queue.
1850 \begin_layout Subsection
1851 gui.loadfont: Load a font file
1854 \begin_layout Itemize
1855 Syntax: CUSTOMFONT gui.loadfont([string filename])
1858 \begin_layout Standard
1859 Loads font from specified file (CUSTOMFONT object).
1860 If filename is not given, loads the system default font.
1863 \begin_layout Subsection
1864 CUSTOMFONT(): Render text to screen
1867 \begin_layout Itemize
1868 Syntax: none CUSTOMFONT(number x, number y, string text[, number fgc[, number
1869 bgc[, number hlc]]])
1872 \begin_layout Standard
1873 Draw string with custom font to screen.
1874 The parameters are the same as in gui.text, except <hlc> is the halo color
1875 (default is no halo).
1879 \begin_layout Subsection
1880 gui.adjust_transparency/DBITMAP:adjust_transparency/PALETTE:adjust_transparency:
1881 Adjust transparency of DBITMAP or PALETTE
1884 \begin_layout Itemize
1885 Syntax: none gui.adjust_transparency(DBITMAP obj, number adj)
1888 \begin_layout Itemize
1889 Syntax: none gui.adjust_transparency(PALETTE obj, number adj)
1892 \begin_layout Itemize
1893 Syntax: none DBITMAP:adjust_transparency(number adj)
1896 \begin_layout Itemize
1897 Syntax: none PALETTE:adjust_transparency(number adj)
1900 \begin_layout Standard
1901 Multiply alpha channel of <obj> by <adj>/256.
1903 \begin_inset Quotes eld
1907 \begin_inset Quotes erd
1910 out of solid bitmaps.
1913 \begin_layout Subsection
1914 gui.kill_frame: Kill video frame and associated sound
1917 \begin_layout Itemize
1918 Syntax: none gui.kill_frame()
1921 \begin_layout Standard
1922 Kills the currently dumped video frame + the associated sound.
1923 Only valid in on_video callback.
1926 \begin_layout Subsection
1927 gui.arrow: Draw an arrow
1930 \begin_layout Itemize
1931 Syntax: none gui.arrow(number x, number y, number length, number hwidth,
1932 number direction[, bool fill[, number color[, number twidth[, number hthick]]]]
1936 \begin_layout Standard
1937 Draws an arrow using color <color>.
1938 The tip of arrow is at (<x>, <y>).
1942 \begin_layout Enumerate
1943 <length>: The length of arrow tail.
1946 \begin_layout Enumerate
1947 <hwidth>: The width of arrow head.
1951 \begin_layout Enumerate
1952 <direction>: Direction of arrow.
1953 0 is to right, +1 rotates 45 degrees counterclockwise.
1956 \begin_layout Enumerate
1957 <fill>: If true, fill the arrow head.
1961 \begin_layout Enumerate
1962 <twidth>: Tail width.
1967 \begin_layout Enumerate
1968 <hthick>: Head thickness (only used if <fill> is false).
1969 Default is <twidth>.
1972 \begin_layout Subsection
1973 gui.tilemap: Create a tilemap
1976 \begin_layout Itemize
1977 Syntax: TILEMAP gui.tilemap(number w, number h, number bw, number bh)
1980 \begin_layout Standard
1981 Create a new tilemap of size <w>*<h>, with each cell being <bw>*<bh>.
1984 \begin_layout Subsection
1985 TILEMAP:getsize: Query tilemap size
1988 \begin_layout Itemize
1989 Syntax: number, number TILEMAP:getsize()
1992 \begin_layout Standard
1993 Return size of tilemap (width first).
1996 \begin_layout Subsection
1997 TILEMAP:getcsize: Query tilemap cell size
2000 \begin_layout Itemize
2001 Syntax: number, number TILEMAP:getcsize()
2004 \begin_layout Standard
2005 Return size of tilemap cell (width first).
2008 \begin_layout Subsection
2009 TILEMAP:get: Query tilemap cell
2012 \begin_layout Itemize
2013 Syntax: none TILEMAP:get(number x, number y)
2016 \begin_layout Itemize
2017 Syntax: dbitmap TILEMAP:get(number x, number y)
2020 \begin_layout Itemize
2021 Syntax: bitmap,palette TILEMAP:get(number x, number y)
2024 \begin_layout Standard
2025 Return contents of cell at <x>,<y>.
2028 \begin_layout Subsection
2029 TILEMAP:set: Set tilemap cell
2032 \begin_layout Itemize
2033 Syntax: none TILEMAP:set(number x, number y)
2036 \begin_layout Itemize
2037 Syntax: none TILEMAP:set(number x, number y, dbitmap b)
2040 \begin_layout Itemize
2041 Syntax: none TILEMAP:set(number x, number y, bitmap b, palette p)
2044 \begin_layout Standard
2045 Set contents of cell at <x>,<y>.
2046 If no bitmap/dbitmap is given, cell is cleared.
2047 Otherwise specified (d)bitmap is used (with specified palette if bitmap).
2050 \begin_layout Subsection
2051 TILEMAP:scroll: Scroll tilemap
2054 \begin_layout Itemize
2055 Syntax: none TILEMAP:scroll(number ox, number oy)
2058 \begin_layout Itemize
2059 Syntax: none TILEMAP:scroll(number ox, number oy, number x, number y, number
2063 \begin_layout Itemize
2064 Syntax: none TILEMAP:scroll(number ox, number oy, number x, number y, number
2065 w, number h, boolean circx, boolean circy)
2068 \begin_layout Standard
2069 Scrolls the tilemap tiles by <ox>,<oy>.
2070 If <x>,<y>,<w>,<h> is specified, the scrolling is limited to <w>*<h> window
2071 starting at <x>,<y> (in tiles).
2074 \begin_layout Standard
2075 If <circx> is true, the window is circular in horizontal direction.
2076 Similarly with <circy> and vertical direciton.
2079 \begin_layout Subsection
2080 TILEMAP:draw: Draw tilemap
2083 \begin_layout Itemize
2084 Syntax: none TILEMAP:draw(number x, number y)
2087 \begin_layout Itemize
2088 Syntax: none TILEMAP:draw(number x, number y, number x0, number y0)
2091 \begin_layout Itemize
2092 Syntax: none TILEMAP:draw(number x, number y, number x0, number y0, number
2096 \begin_layout Standard
2097 Draw tilemap at <x>,<y>.
2098 If <x0>,<y0> is given, that is tilemap coordinate (in pixels) of upper
2100 If <w>,<h> is given, that is the size of window to draw (in pixels)
2103 \begin_layout Subsection
2104 gui.bitmap_save_png/(D)BITMAP:save_png: Save a bitmap to PNG
2107 \begin_layout Itemize
2108 Syntax: none gui.bitmap_save_png(string filename[, string base], BITMAP bmp,
2112 \begin_layout Itemize
2113 Syntax: none gui.bitmap_save_png(string filename[, string base], DBITMAP
2117 \begin_layout Itemize
2118 Syntax: string gui.bitmap_save_png(BITMAP bmp, PALETTE pal)
2121 \begin_layout Itemize
2122 Syntax: string gui.bitmap_save_png(DBITMAP bmp)
2125 \begin_layout Itemize
2126 Syntax: none BITMAP:save_png(string filename[, string base], PALETTE pal)
2129 \begin_layout Itemize
2130 Syntax: none DBITMAP:save_png(string filename[, string base])
2133 \begin_layout Itemize
2134 Syntax: string BITMAP:save_png(PALETTE pal)
2137 \begin_layout Itemize
2138 Syntax: string DBITMAP:save_png()
2141 \begin_layout Standard
2142 Save specified bitmap <bmp> (or current object), with palette <pal> (only
2143 if paletted) into PNG file <filename> (relative to <base>) or return BASE64
2144 encoding as return value.
2147 \begin_layout Subsection
2148 gui.bitmap_hash/(D)BITMAP:hash: Hash a bitmap
2151 \begin_layout Itemize
2152 Syntax: string gui.bitmap_hash(BITMAP bmp)
2155 \begin_layout Itemize
2156 Syntax: string gui.bitmap_hash(DBITMAP bmp)
2159 \begin_layout Itemize
2160 Syntax: string BITMAP:hash()
2163 \begin_layout Itemize
2164 Syntax: string DBITMAP:hash()
2167 \begin_layout Standard
2168 Hashes bitmap <bmp> (or current object) and returns 64-hex digit crypto-strong
2170 Identical bitmaps result in indentical hashes (but color order in indexed
2171 bitmaps is significant).
2174 \begin_layout Subsection
2175 gui.palette_hash/PALETTE:hash: Hash a palette
2178 \begin_layout Itemize
2179 Syntax: string gui.palette_hash(PALETTE pal)
2182 \begin_layout Itemize
2183 Syntax: string PALETTE:hash(PALETTE pal)
2186 \begin_layout Standard
2187 Hashes palette <pal> (or current object) and retruns 64-hex digit crypto-strong
2189 Identical palettes result in identical hashes (fully transparent colors
2190 at end of palette don't affect the hash).
2193 \begin_layout Standard
2194 \begin_inset Newpage pagebreak
2200 \begin_layout Section
2204 \begin_layout Standard
2206 Functions manipulating input are only available in on_input callback.
2209 \begin_layout Subsection
2210 input.get: Read controller button/axis (deprecated)
2213 \begin_layout Itemize
2214 Syntax: number input.get(number controller, number index)
2217 \begin_layout Standard
2218 Read the specified index <index> (zero-based) from specified controller
2219 <controller> (zero-based).
2223 \begin_layout Subsection
2224 input.set: Write controller button/axis (deprecated)
2227 \begin_layout Itemize
2228 Syntax: none input.set(number controller, number index, number value)
2231 \begin_layout Standard
2232 Write the specified index <index> (zero-based) from specified controller
2233 <controller> (zero-based), storing value <value>.
2236 \begin_layout Subsection
2237 input.get2: Read controller button/axis
2240 \begin_layout Itemize
2241 Syntax: number input.get2(number port, number controller, number index)
2244 \begin_layout Standard
2245 Read the specified input tuple.
2246 Port 0 is system port.
2249 \begin_layout Subsection
2250 input.set2: Write controller button/axis
2253 \begin_layout Itemize
2254 Syntax: input.set2(number port, number controller, number index, number value)
2257 \begin_layout Standard
2258 Write the specified input tuple.
2259 Port 0 is system port.
2262 \begin_layout Subsection
2263 input.lcid_to_pcid2: Look up logical controller
2266 \begin_layout Itemize
2267 Syntax: (number, number) input.lcid_to_pcid2(number lcid)
2270 \begin_layout Standard
2271 Look up physical pcid pair (port, controller) corresponding to specified
2272 logical controller (1-based).
2273 Returns nothing if controller does not exist.
2276 \begin_layout Subsection
2277 input.port_type: Look up port type
2280 \begin_layout Itemize
2281 Syntax: string input.port_type(number port)
2284 \begin_layout Standard
2285 Return type of specified port.
2288 \begin_layout Subsection
2289 input.controller_info: Get information about controller
2292 \begin_layout Itemize
2293 Syntax: table input.controller_info(number port, number controller)
2296 \begin_layout Standard
2297 Get controller info for specified controller.
2298 If controller does not exist, returns nil.
2299 Otherwise returns a table with following fields:
2302 \begin_layout Itemize
2303 type (string): Type of the controller.
2306 \begin_layout Itemize
2307 class (string): Class of the controller.
2310 \begin_layout Itemize
2311 classnum (number): Number of the controller within its class (1-based)
2314 \begin_layout Itemize
2315 lcid (number): Logical controller number of the controller.
2318 \begin_layout Itemize
2319 button_count (number): Number of buttons on controller
2322 \begin_layout Itemize
2323 buttons (array): Array of following info about each button:
2327 \begin_layout Itemize
2328 type (string): Type of button.
2330 \begin_inset Quotes eld
2334 \begin_inset Quotes erd
2338 \begin_inset Quotes eld
2342 \begin_inset Quotes erd
2346 \begin_inset Quotes eld
2350 \begin_inset Quotes erd
2354 \begin_inset Quotes eld
2358 \begin_inset Quotes erd
2364 \begin_layout Itemize
2365 name (string): Name of button.
2368 \begin_layout Itemize
2369 symbol (string): Symbol of button.
2370 Only present for type
2371 \begin_inset Quotes eld
2375 \begin_inset Quotes erd
2381 \begin_layout Itemize
2382 hidden (boolean): True if hidden button.
2387 \begin_layout Subsection
2388 input.veto_button: Veto a button press
2391 \begin_layout Itemize
2392 Syntax: none input.veto_button()
2395 \begin_layout Standard
2396 Signals that the button event should be vetoed.
2397 Only valid in on_button callback.
2400 \begin_layout Subsection
2401 input.geta: Get all buttons for controller (deprecated)
2404 \begin_layout Itemize
2405 Syntax: (number, number...) input.geta(number controller)
2408 \begin_layout Standard
2409 Get input state for entiere controller.
2410 Returns n return values.
2413 \begin_layout Itemize
2414 1st return value: Bitmask: bit i is set if i:th index is nonzero
2417 \begin_layout Itemize
2418 2nd- return value: value of i:th index.
2421 \begin_layout Subsection
2422 input.seta: Set all buttons for controller (deprecated)
2425 \begin_layout Itemize
2426 Syntax: none input.seta(number controller, number bitmask, number args...)
2429 \begin_layout Standard
2430 Set state for entiere controller.
2431 args is up to N values for indices (overriding values in bitmask if specified).
2434 \begin_layout Subsection
2435 input.controllertype: Get controller type (deprecated)
2438 \begin_layout Itemize
2439 syntax: string input.controllertype(number controller)
2442 \begin_layout Standard
2443 Get the type of controller as string.
2446 \begin_layout Subsection
2447 input.reset: Execute (delayed) reset
2450 \begin_layout Itemize
2451 Syntax: none input.reset([number cycles])
2454 \begin_layout Standard
2456 If <cycles> is greater than zero, do delayed reset.
2457 0 (or no value) causes immediate reset.
2460 \begin_layout Itemize
2461 Note: Only available with subframe flag false.
2464 \begin_layout Subsection
2465 input.raw: Return raw input data
2468 \begin_layout Itemize
2469 Syntax: table input.raw()
2472 \begin_layout Standard
2473 Returns table of tables of all available keys and axes.
2474 The first table is indexed by key name (platform-dependent!), and the inner
2475 table has the following fields:
2478 \begin_layout Itemize
2479 value: Last reported value for control
2483 \begin_layout Itemize
2484 For keys: 1 for pressed, 0 for released.
2487 \begin_layout Itemize
2488 For axes: -32767...32767.
2491 \begin_layout Itemize
2492 For presure-sensitive buttons: 0...32767.
2495 \begin_layout Itemize
2496 For hats: Bitmask: 1=>Up, 2=>Right, 4=>Down, 8=>Left.
2499 \begin_layout Itemize
2500 For mouse: Coordinates relative to game area.
2504 \begin_layout Itemize
2505 ktype: Type of key (disabled, key, mouse, axis, hat, pressure).
2508 \begin_layout Subsection
2509 input.keyhook: Hook a key
2512 \begin_layout Itemize
2513 Syntax: none input.keyhook(string key, boolean state)
2516 \begin_layout Standard
2517 Requests that keyhook events to be sent for key <key> (<state>=true) or
2518 not sent (<state>=false).
2521 \begin_layout Subsection
2522 input.joyget: Get controls for controller
2525 \begin_layout Itemize
2526 Syntax: table input.joyget(number logical)
2529 \begin_layout Standard
2530 Returns table for current controls for specified logical controller <logical>.
2531 The names of fields vary by controller type.
2534 \begin_layout Itemize
2535 The buttons have the same name as those are referred to in other contexts
2539 \begin_layout Itemize
2540 The analog axes are usually
2541 \begin_inset Quotes eld
2545 \begin_inset Quotes erd
2549 \begin_inset Quotes eld
2553 \begin_inset Quotes erd
2559 \begin_layout Itemize
2560 Each field is numeric or boolean depending on axis/button.
2563 \begin_layout Subsection
2564 input.joyset: Set controls for controller
2567 \begin_layout Itemize
2568 Syntax: none input.joyset(number controller, table controls)
2571 \begin_layout Standard
2572 Set the the state of specified controller to values specified in specified
2576 \begin_layout Itemize
2577 Each field can be boolean or number.
2580 \begin_layout Itemize
2581 Also, buttons allow strings, which cause value to be inverted.
2584 \begin_layout Subsection
2585 input.lcid_to_pcid: Look up logical controller (deprecated)
2588 \begin_layout Itemize
2589 Syntax: (number, number, number) input.lcid_to_pcid(number lcid)
2592 \begin_layout Standard
2593 Returns the legacy pcid for controller (or false if there isn't one), followed
2595 Returns nothing if controller does not exist.
2598 \begin_layout Standard
2599 \begin_inset Newpage pagebreak
2605 \begin_layout Section
2609 \begin_layout Standard
2610 Various keybinding-related functions
2613 \begin_layout Subsection
2614 keyboard.bind: Bind a key
2617 \begin_layout Itemize
2618 Syntax: none keyboard.bind(string mod, string mask, string key, string cmd)
2621 \begin_layout Standard
2622 Bind specified key with specified modifers to specified command.
2625 \begin_layout Subsection
2626 keyboard.unbind: Unbind a key
2629 \begin_layout Itemize
2630 Syntax: none keyboard.unbind(string mod, string mask, string key)
2633 \begin_layout Standard
2634 Unbind specified key with specified modifers.
2637 \begin_layout Subsection
2638 keyboard.alias: Set alias expansion
2641 \begin_layout Itemize
2642 Syntax: none keyboard.alias(string alias, string expansion)
2645 \begin_layout Standard
2646 Set expansion of given command.
2649 \begin_layout Standard
2650 \begin_inset Newpage pagebreak
2656 \begin_layout Section
2660 \begin_layout Standard
2664 \begin_layout Subsection
2665 subtitle.byindex: Look up start and length of subtitle by index
2668 \begin_layout Itemize
2669 Syntax: (number, number) subtitle.byindex(number i)
2672 \begin_layout Standard
2673 Read the frame and length of ith subtitle.
2674 Returns nothing if not present.
2677 \begin_layout Subsection
2678 subtitle.set: Write a subtitle
2681 \begin_layout Itemize
2682 Syntax: none subtitle.set(number f, number l, string txt)
2685 \begin_layout Standard
2686 Set the text of subtitle.
2689 \begin_layout Subsection
2690 subtitle.get: Read a subtitle
2693 \begin_layout Itemize
2694 Syntax: string subtitle.get(number f, number l)
2697 \begin_layout Standard
2698 Get the text of subtitle.
2701 \begin_layout Subsection
2702 subtitle.delete: Delete a subtitle
2705 \begin_layout Itemize
2706 Syntax: nonesubtitle.delete(number f, number l)
2709 \begin_layout Standard
2710 Delete specified subtitle.
2713 \begin_layout Standard
2714 \begin_inset Newpage pagebreak
2720 \begin_layout Section
2724 \begin_layout Standard
2725 Host memory handling (extra memory saved to savestates).
2726 Host memory starts empty.
2729 \begin_layout Itemize
2730 Reads out of range return false.
2733 \begin_layout Itemize
2734 Writes out of range extend the memory.
2737 \begin_layout Subsection
2738 hostmemory.read: Read byte from host memory
2741 \begin_layout Itemize
2742 Syntax: number hostmemory.read(number address)
2745 \begin_layout Standard
2746 Reads byte from hostmemory slot address <address>.
2749 \begin_layout Subsection
2750 hostmemory.write: Write byte to host memory
2753 \begin_layout Itemize
2754 Syntax: none hostmemory.write(number address, number value)
2757 \begin_layout Standard
2758 Writes hostmemory slot with value <value> 0-255.
2761 \begin_layout Subsection
2762 hostmemory.read{,s}{byte,{,h,d,q}word}: Read from host memory
2765 \begin_layout Itemize
2766 Syntax: number hostmemory.readbyte(number address)
2769 \begin_layout Itemize
2770 Syntax: number hostmemory.readsbyte(number address)
2773 \begin_layout Itemize
2774 Syntax: number hostmemory.readword(number address)
2777 \begin_layout Itemize
2778 Syntax: number hostmemory.readsword(number address)
2781 \begin_layout Itemize
2782 Syntax: number hostmemory.readhword(number address)
2785 \begin_layout Itemize
2786 Syntax: number hostmemory.readshword(number address)
2789 \begin_layout Itemize
2790 Syntax: number hostmemory.readdword(number address)
2793 \begin_layout Itemize
2794 Syntax: number hostmemory.readsdword(number address)
2797 \begin_layout Itemize
2798 Syntax: number hostmemory.readqword(number address)
2801 \begin_layout Itemize
2802 Syntax: number hostmemory.readsqword(number address)
2805 \begin_layout Standard
2806 Read elements (big-endian) from given address <address>.
2809 \begin_layout Itemize
2813 \begin_layout Itemize
2817 \begin_layout Itemize
2821 \begin_layout Itemize
2825 \begin_layout Itemize
2826 qword is 8 elements.
2829 \begin_layout Itemize
2830 The 's' variants do signed read.
2833 \begin_layout Subsection
2834 hostmemory.read{float,double}: Read from host memory
2837 \begin_layout Itemize
2838 syntax: number hostmemory.readfloat(number address)
2841 \begin_layout Itemize
2842 Syntax: number hostmemory.readdouble(number address)
2845 \begin_layout Standard
2846 Read elements (big-endian) floating-pont from given address <address>.
2849 \begin_layout Subsection
2850 hostmemory.write{,s}{byte,{,h,d,q}word}: Write to host memory
2853 \begin_layout Itemize
2854 Syntax: number hostmemory.writebyte(number address, number value)
2857 \begin_layout Itemize
2858 Syntax: number hostmemory.writesbyte(number address, number value)
2861 \begin_layout Itemize
2862 Syntax: number hostmemory.writeword(number address, number value)
2865 \begin_layout Itemize
2866 Syntax: number hostmemory.writesword(number address, number value)
2869 \begin_layout Itemize
2870 Syntax: number hostmemory.writehword(number address, number value)
2873 \begin_layout Itemize
2874 Syntax: number hostmemory.writeshword(number address, number value)
2877 \begin_layout Itemize
2878 Syntax: number hostmemory.writedword(number address, number value)
2881 \begin_layout Itemize
2882 Syntax: number hostmemory.writesdword(number address, number value)
2885 \begin_layout Itemize
2886 Syntax: number hostmemory.writeqword(number address, number value)
2889 \begin_layout Itemize
2890 Syntax: number hostmemory.writesqword(number address, number value)
2893 \begin_layout Standard
2894 Write value <value> to elements (little-endian) starting from given address
2898 \begin_layout Itemize
2902 \begin_layout Itemize
2906 \begin_layout Itemize
2910 \begin_layout Itemize
2914 \begin_layout Itemize
2915 qword is 8 elements.
2918 \begin_layout Itemize
2919 The 's' variants do signed write.
2922 \begin_layout Subsection
2923 hostmemory.write{float,double}: Write to host memory
2926 \begin_layout Itemize
2927 syntax: none hostmemory.readfloat(number address, number value)
2930 \begin_layout Itemize
2931 Syntax: none hostmemory.readdouble(number address, number value)
2934 \begin_layout Standard
2935 Write elements (big-endian) floating-pont to given address <address>, storing
2939 \begin_layout Standard
2940 \begin_inset Newpage pagebreak
2946 \begin_layout Section
2950 \begin_layout Standard
2954 \begin_layout Subsection
2955 movie.currentframe: Get current frame number
2958 \begin_layout Itemize
2959 Syntax: number movie.currentframe()
2962 \begin_layout Standard
2963 Return number of current frame.
2966 \begin_layout Subsection
2967 movie.framecount: Get move frame count
2970 \begin_layout Itemize
2971 Syntax: number movie.framecount()
2974 \begin_layout Standard
2975 Return number of frames in movie.
2978 \begin_layout Subsection
2979 movie.readonly: Is in readonly mode?
2982 \begin_layout Itemize
2983 Syntax: boolean movie.readonly()
2986 \begin_layout Standard
2987 Return true if in readonly mode, false if in readwrite.
2990 \begin_layout Subsection
2991 movie.rerecords: Movie rerecord count
2994 \begin_layout Itemize
2995 Syntax: number movie.rerecords()
2998 \begin_layout Standard
2999 Returns the current value of rerecord count.
3002 \begin_layout Subsection
3003 movie.set_readwrite: Set read-write mode.
3006 \begin_layout Itemize
3007 Syntax: none movie.set_readwrite()
3010 \begin_layout Standard
3011 Set readwrite mode (does not cause on_readwrite callback).
3014 \begin_layout Subsection
3015 movie.frame_subframes: Count subframes in frame
3018 \begin_layout Itemize
3019 Syntax: number movie.frame_subframes(number frame)
3022 \begin_layout Standard
3023 Count number of subframes in specified frame <frame> (frame numbers are
3024 1-based) and return that.
3027 \begin_layout Subsection
3028 movie.read_subframes: Read subframe data (deprecated)
3031 \begin_layout Itemize
3032 Syntax: table movie.read_subframes(number frame, number subframe)
3035 \begin_layout Standard
3036 Read specifed subframe in specified frame and return data as array.
3039 \begin_layout Subsection
3040 movie.read_rtc: Read current RTC time
3043 \begin_layout Itemize
3044 Syntax: (number, number) movie.read_rtc()
3047 \begin_layout Standard
3048 Returns the current value of the RTC as a pair (second, subsecond).
3051 \begin_layout Subsection
3052 movie.unsafe_rewind: Fast movie rewind to saved state
3055 \begin_layout Itemize
3056 Syntax: none movie.unsafe_rewind([UNSAFEREWIND state])
3059 \begin_layout Standard
3060 Start setting point for unsafe rewind or jump to point of unsafe rewind.
3063 \begin_layout Itemize
3064 If called without argument, causes emulator to start process of setting
3065 unsafe rewind point.
3066 When this has finished, callback on_set_rewind occurs, passing the rewind
3067 state to lua script.
3070 \begin_layout Itemize
3071 If called with argument, causes emulator rewind to passed rewind point as
3073 Readwrite mode is implicitly activated.
3076 \begin_layout Standard
3077 The following warnings apply to unsafe rewinding:
3080 \begin_layout Itemize
3081 There are no safety checks against misuse (that's what
3082 \begin_inset Quotes eld
3086 \begin_inset Quotes erd
3092 \begin_layout Itemize
3093 Only call rewind from timeline rewind point was set from.
3096 \begin_layout Itemize
3097 Only call rewind from after the rewind point was set.
3100 \begin_layout Subsection
3101 movie.to_rewind: Load savestate as rewind point
3104 \begin_layout Itemize
3105 Syntax: UNSAFEREWIND movie.to_rewind(string filename)
3108 \begin_layout Standard
3109 Load specified savestate file <filename> as rewind point and return UNSAFEREWIND
3110 corresponding to it.
3113 \begin_layout Itemize
3114 Note: This operation does not take emulated time.
3117 \begin_layout Subsection
3118 movie.copy_movie/INPUTMOVIE::copy_movie: Copy movie to movie object
3121 \begin_layout Itemize
3122 Syntax: INPUTMOVIE movie.copy_movie([INPUTMOVIE movie])
3125 \begin_layout Itemize
3126 Syntax: INPUTMOVIE INPUTMOVIE::copy_movie()
3129 \begin_layout Standard
3130 Copies specified movie <movie>/current object (if none or nil, the active
3131 movie) as new movie object.
3134 \begin_layout Subsection
3135 movie.get_frame/INPUTMOVIE::get_frame: Read specified frame in movie.
3138 \begin_layout Itemize
3139 Syntax: INPUTFRAME movie.get_frame([INPUTMOVIE movie,] number frame)
3142 \begin_layout Itemize
3143 Syntax: INPUTFRAME INPUTMOVIE::get_frame(number frame);
3146 \begin_layout Standard
3147 Get INPUTFRAME object corresponding to specified frame in specified movie.
3150 \begin_layout Subsection
3151 movie.set_frame/INPUTMOVIE::set_frame: Write speicifed frame in movie.
3154 \begin_layout Itemize
3155 Syntax: none movie.set_frame([INPUTMOVIE movie,] number frame, INPUTFRAME
3159 \begin_layout Itemize
3160 Syntax: none INPUTMOVIE::set_frame(number frame, INPUTFRAME data)
3163 \begin_layout Standard
3164 Set data in specified frame.
3167 \begin_layout Itemize
3168 Note: Past can't be edited in active movie.
3171 \begin_layout Subsection
3172 movie.get_size/INPUTMOVIE::get_size: Get size of movie
3175 \begin_layout Itemize
3176 Syntax: integer movie.get_size([INPUTMOVIE movie])
3179 \begin_layout Itemize
3180 Syntax: integer INPUTMOVIE::get_size()
3183 \begin_layout Standard
3184 Return number of subframes in specified movie.
3187 \begin_layout Subsection
3188 movie.count_frames/INPUTMOVIE::count_frames: Count frames in movie
3191 \begin_layout Itemize
3192 Syntax: number movie.count_frames([INPUTMOVIE movie])
3195 \begin_layout Itemize
3196 Syntax: number INPUTMOVIE::count_frames()
3199 \begin_layout Standard
3200 Return number of frames in movie.
3203 \begin_layout Subsection
3204 movie.find_frame/INPUTMOVIE::find_frame: Find subframe corresponding to frame
3207 \begin_layout Itemize
3208 Syntax: number movie.find_frame([INPUTMOVIE movie], number frame)
3211 \begin_layout Itemize
3212 Syntax: number INPUTMOVIE::find_frame(number frame)
3215 \begin_layout Standard
3216 Returns starting subframe of given frame (frame numbers are 1-based).
3217 Returns -1 if frame number is bad.
3220 \begin_layout Subsection
3221 movie.blank_frame/INPUTMOVIE::blank_frame: Return a blank frame
3224 \begin_layout Itemize
3225 Syntax: INPUTFRAME movie.blank_frame([INPUTMOVIE movie])
3228 \begin_layout Itemize
3229 Syntax: INPUTFRAME INPUTMOVIE::blank_frame()
3232 \begin_layout Standard
3233 Return blank INPUTFRAME with frame type from specified movie.
3236 \begin_layout Subsection
3237 movie.append_frames/INPUTMOVIE::append_frames: Append blank frames
3240 \begin_layout Itemize
3241 Syntax: none movie.append_frames([INPUTMOVIE movie,] number frames)
3244 \begin_layout Itemize
3245 Syntax: none INPUTMOVIE::append_frames(number frames)
3248 \begin_layout Standard
3249 Append specified number <frames> of frames.
3252 \begin_layout Subsection
3253 movie.append_frame/INPUTMOVIE::append_frame: Append a frame
3256 \begin_layout Itemize
3257 Syntax: none movie.append_frame([INPUTMOVIE movie,] INPUTFRAME frame)
3260 \begin_layout Itemize
3261 Syntax: none INPUTMOVIE::append_frame(INPUTFRAME frame)
3264 \begin_layout Standard
3265 Append specified frame <frame>.
3266 Past of current movie can't be edited.
3269 \begin_layout Subsection
3270 movie.truncate/INPUTMOVIE::truncate: Truncate a movie.
3273 \begin_layout Itemize
3274 Syntax: none movie.truncate([INPUTMOVIE movie,] number frames)
3277 \begin_layout Itemize
3278 Syntax: none INPUTMOVIE::truncate(number frames)
3281 \begin_layout Standard
3282 Truncate the specified movie to specified number of frames.
3285 \begin_layout Subsection
3286 movie.edit/INPUTMOVIE::edit: Edit a movie
3289 \begin_layout Itemize
3290 Syntax: none movie.edit([INPUTMOVIE movie,] number frame, number port, number
3291 controller, number control, number/bool value)
3294 \begin_layout Itemize
3295 Syntax: none INPUTMOVIE::edit(number frame, number port, number controller,
3296 number control, number/bool value)
3299 \begin_layout Standard
3300 Change specified control in specified frame in specified movie.
3301 Past can't be edited in active movie.
3304 \begin_layout Subsection
3305 movie.copy_frames2: Copy frames between movies
3308 \begin_layout Itemize
3309 Syntax: none movie.copy_frames2([INPUTMOVIE dstmov,] number dst, [INPUTMOVIE
3310 srcmov,] number src, number count)
3313 \begin_layout Standard
3314 Copy specified number of frames between two movies.
3315 The copy proceeeds in forward direction.
3318 \begin_layout Subsection
3319 movie.copy_frames/INPUTMOVIE::copy_frames: Copy frames in movie
3322 \begin_layout Itemize
3323 Syntax: none movie.copy_frames([INPUTMOVIE mov,] number dst, number src,
3324 number count, bool backwards)
3327 \begin_layout Itemize
3328 Syntax: none INPUTMOVIE::copy_frames(number dst, number src, number count,
3332 \begin_layout Standard
3333 Copy specified number of frames from one point in movie to another.
3334 If backwards is true, the copy will be done backwards.
3337 \begin_layout Subsection
3338 movie.serialize/INPUTMOVIE::serialize: Serialize movie
3341 \begin_layout Itemize
3342 Syntax: none movie.serialize([INPUTMOVIE movie,] string filename, bool binary)
3345 \begin_layout Itemize
3346 Syntax: none INPUTMOIVE::serialize(string filename, bool binary)
3349 \begin_layout Standard
3350 Serialize given movie into file.
3351 If binary is true, binary format (more compact and much faster) is used.
3354 \begin_layout Subsection
3355 movie.unserialize: Unserialize movie
3358 \begin_layout Itemize
3359 Syntax: INPUTMOVIE movie.unserialize(INPUTFRAME template, string filename,
3363 \begin_layout Standard
3364 Unserialize movie from file.
3365 The given frame is used as template to decide the frame type.
3366 If binary is true, binary format is decoded (much faster).
3369 \begin_layout Subsection
3370 movie.current_first_subframe: Return first subframe in current frame
3373 \begin_layout Itemize
3374 Syntax: number movie.current_first_subframe()
3377 \begin_layout Standard
3378 Returns first subframe in current frame.
3381 \begin_layout Subsection
3382 movie.pollcounter: Return poll counter for speified control
3385 \begin_layout Itemize
3386 Syntax: number movie.pollcounter(number port, number controller, number control)
3389 \begin_layout Standard
3390 Returns number of times the specified control has been polled this frame.
3393 \begin_layout Subsection
3394 INPUTFRAME::get_button: Get button
3397 \begin_layout Itemize
3398 Syntax: boolean INPUTFRAME::get_button(number port, number controller, number
3402 \begin_layout Standard
3403 Returns state of given button as boolean.
3406 \begin_layout Subsection
3407 INPUTFRAME::get_axis: Get axis
3410 \begin_layout Itemize
3411 Syntax: number INPUTFRAME::get_axis(number port, number controller, number
3415 \begin_layout Standard
3416 Returns state of given axis as number.
3419 \begin_layout Subsection
3420 INPUTFRAME::set_button/INPUTFRAME::set_axis: Set button or axis
3423 \begin_layout Itemize
3424 Syntax: none INPUTFRAME::set_button(number port, number controller, number
3425 control, number/bool value)
3428 \begin_layout Itemize
3429 Syntax: none INPUTFRAME::set_axis(number port, number controller, number
3433 \begin_layout Standard
3434 Set the given button/axis to given value.
3437 \begin_layout Subsection
3438 INPUTFRAME::serialize: Serialize a frame
3441 \begin_layout Itemize
3442 Syntax: string INPUTFRAME::serialize()
3445 \begin_layout Standard
3446 Return string representation of frame.
3449 \begin_layout Subsection
3450 INPUTFRAME::unserialize: Unserialize a frame
3453 \begin_layout Itemize
3454 Syntax: none INPUTFRAME::unserialize(string data)
3457 \begin_layout Standard
3458 Set current frame from given data.
3461 \begin_layout Subsection
3462 INPUTFRAME::get_stride: Get movie stride
3465 \begin_layout Itemize
3466 Syntax: number INPUTFRAME::get_stride()
3469 \begin_layout Standard
3470 Return number of bytes needed to store the input frame.
3471 Mainly useful for some debugging.
3474 \begin_layout Standard
3475 \begin_inset Newpage pagebreak
3481 \begin_layout Section
3485 \begin_layout Standard
3486 Routines for settings manipulation
3489 \begin_layout Subsection
3490 settings.get: Get value of setting
3493 \begin_layout Itemize
3494 Syntax: string settings.get(string name)
3497 \begin_layout Standard
3498 Get value of setting <name>.
3499 If setting value can't be obtained, returns (nil, error message).
3502 \begin_layout Subsection
3503 settings.set: Set value of setting
3506 \begin_layout Itemize
3507 Syntax: none settings.set(string name, string value)
3510 \begin_layout Standard
3511 Set value <value> of setting <name>.
3512 If setting can't be set, returns (nil, error message).
3515 \begin_layout Standard
3516 \begin_inset Newpage pagebreak
3522 \begin_layout Section
3526 \begin_layout Standard
3527 Contains various functions for managing memory
3530 \begin_layout Subsection
3531 memory.vma_count: Count number of VMAs.
3534 \begin_layout Itemize
3535 Syntax: number memory.vma_count()
3538 \begin_layout Standard
3539 Returns the number of VMAs
3542 \begin_layout Subsection
3543 memory.read_vma: Lookup VMA info by index
3546 \begin_layout Itemize
3547 Syntax: string memory.read_vma(number index)
3550 \begin_layout Standard
3551 Reads the specified VMA (indices start from zero).
3552 Trying to read invalid VMA gives nil.
3553 The read VMA is table with the following fields:
3556 \begin_layout Itemize
3557 region_name (string): The readable name of the VMA
3560 \begin_layout Itemize
3561 baseaddr (number): Base address of the VMA
3564 \begin_layout Itemize
3565 lastaddr (number): Last address in the VMA.
3568 \begin_layout Itemize
3569 size (number): The size of VMA in bytes.
3572 \begin_layout Itemize
3573 readonly (boolean): True of the VMA corresponds to ROM.
3576 \begin_layout Itemize
3577 iospace (boolean): True if the VMA is I/O space.
3580 \begin_layout Itemize
3581 native_endian (boolean): True if the VMA has native endian as opposed to
3585 \begin_layout Subsection
3586 memory.find_vma: Find VMA info by address
3589 \begin_layout Itemize
3590 Syntax: table memory.find_vma(number address)
3593 \begin_layout Standard
3594 Finds the VMA containing specified address.
3595 Returns table in the same format as read_vma or nil if not found.
3598 \begin_layout Subsection
3599 memory.read{,s}{byte,{,h,d,q}word}: Read memory
3602 \begin_layout Itemize
3603 Syntax: none memory.readbyte([string vma, ]number address)
3606 \begin_layout Itemize
3607 Syntax: none memory.readword([string vma, ]number address)
3610 \begin_layout Itemize
3611 Syntax: none memory.readhword([string vma, ]number address)
3614 \begin_layout Itemize
3615 Syntax: none memory.readdword([string vma, ]number address)
3618 \begin_layout Itemize
3619 Syntax: none memory.readqword([string vma, ]number address)
3622 \begin_layout Itemize
3623 Syntax: none memory.readsbyte([string vma, ]number address)
3626 \begin_layout Itemize
3627 Syntax: none memory.readsword([string vma, ]number address)
3630 \begin_layout Itemize
3631 Syntax: none memory.readshword([string vma, ]number address)
3634 \begin_layout Itemize
3635 Syntax: none memory.readsdword([string vma, ]number address)
3638 \begin_layout Itemize
3639 Syntax: none memory.readsqword([string vma, ]number address)
3642 \begin_layout Standard
3643 Reads the specified address <address> (if 's' variant is used, do undergo
3647 \begin_layout Subsection
3648 memory.{,s}read_sg: Scatter/Gather read memory
3651 \begin_layout Itemize
3652 Syntax: none memory.read_sg(string/boolean/number...)
3655 \begin_layout Itemize
3656 Syntax: none memory.sread_sg(string/boolean/number...)
3659 \begin_layout Standard
3660 Perform (2s complement signed if using memory.sread_sg) scatter/gather read
3662 Each argument can be string, boolean or number:
3665 \begin_layout Itemize
3666 String: Set VMA addresses are relative to (e.g.
3670 \begin_layout Itemize
3671 boolean: If true, increment relative address by 1, if false, decrement by
3673 The new address is read as next higher byte.
3676 \begin_layout Itemize
3677 integer: Set the relative address to specified value and read the address
3678 as next higher byte.
3681 \begin_layout Subsection
3682 memory.write_sg: Scatter/Gather write memory
3685 \begin_layout Itemize
3686 Syntax: none memory.write_sg(number value, string/boolean/number...)
3689 \begin_layout Standard
3690 Perform scatter/gather write of value <value> on memory.
3691 Each argument can be string, boolean or number:
3694 \begin_layout Itemize
3695 String: Set VMA addresses are relative to (e.g.
3699 \begin_layout Itemize
3700 boolean: If true, increment relative address by 1, if false, decrement by
3702 The new address is read as next higher byte.
3705 \begin_layout Itemize
3706 integer: Set the relative address to specified value and read the address
3707 as next higher byte.
3710 \begin_layout Subsection
3711 memory.read{float,double}: Read memory
3714 \begin_layout Itemize
3715 Syntax: none memory.readfloat([string vma, ]number address)
3718 \begin_layout Itemize
3719 Syntax: none memory.readdouble([string vma, ]number address)
3722 \begin_layout Standard
3723 Reads the specified address <address>
3726 \begin_layout Subsection
3727 memory.write{byte,{,h,d,q}word,float,double}: Write memory
3730 \begin_layout Itemize
3731 Syntax: none memory.writebyte([string vma, ]number address, number value)
3734 \begin_layout Itemize
3735 Syntax: none memory.writeword([string vma, ]number address, number value)
3738 \begin_layout Itemize
3739 Syntax: none memory.writehword([string vma, ]number address, number value)
3742 \begin_layout Itemize
3743 Syntax: none memory.writedword([string vma, ]number address, number value)
3746 \begin_layout Itemize
3747 Syntax: none memory.writeqword([string vma, ]number address, number value)
3750 \begin_layout Itemize
3751 Syntax: none memory.writefloat([string vma, ]number address, number value)
3754 \begin_layout Itemize
3755 Syntax: none memory.writedouble([string vma, ]number address, number value)
3758 \begin_layout Standard
3759 Writes the specified value <value> (negative integer values undergo 2's
3760 complement) to specified address <address>.
3763 \begin_layout Subsection
3764 memory.map{{,s}{byte,{,h,d,q}word},float,double}: Map an array
3767 \begin_layout Itemize
3768 Syntax: userdata memory.map<type>([[string vma, ]number base, number size])
3771 \begin_layout Standard
3772 Returns a table mapping specified memory aperture for read/write.
3773 If parameters are omitted, entiere map space is the aperture.
3776 \begin_layout Itemize
3777 Type may be one of: byte, sbyte, word, sword, hword, shword, dword, sdword,
3778 qword, sqword, float or double.
3781 \begin_layout Subsection
3782 memory.hash_region: Hash region of memory
3785 \begin_layout Itemize
3786 Syntax: string memory.hash_region([string vma, ]number base, number size)
3789 \begin_layout Standard
3790 Hash specified number of bytes starting from specified address and return
3794 \begin_layout Subsection
3795 memory.hash_state: Hash system state
3798 \begin_layout Itemize
3799 Syntax: string memory.hash_state()
3802 \begin_layout Standard
3803 Hash the current system state.
3804 Mainly useful for debugging savestates.
3807 \begin_layout Subsection
3808 memory.readregion: Read region of memory
3811 \begin_layout Itemize
3812 Syntax: table memory.readregion([string vma, ]number base, number size)
3815 \begin_layout Standard
3816 Read a region of memory.
3819 \begin_layout Itemize
3820 Warning: If the region crosses VMA boundary, the results are undefined.
3823 \begin_layout Subsection
3824 memory.writeregion: Write region of memory
3827 \begin_layout Itemize
3828 Syntax: none memory.writeregion([string vma, ]number base, number size, table
3832 \begin_layout Standard
3833 Write a region of memory.
3836 \begin_layout Itemize
3837 Warning: If the region crosses VMA boundary, the results are undefined.
3840 \begin_layout Subsection
3841 memory.map_structure: Create mmap structure
3844 \begin_layout Itemize
3845 syntax: MMAP_STRUCT memory.map_structure()
3848 \begin_layout Standard
3849 Returns a new mapping structure (MMAP_STRUCT)
3852 \begin_layout Subsection
3853 MMAP_STRUCT(): Bind key in mmap structure
3856 \begin_layout Itemize
3857 Syntax: none MMAP_STRUCT(string key, [string vma, ]number address, string
3861 \begin_layout Standard
3862 Bind key <key> in mmap structure to specified address <address> with specified
3866 \begin_layout Itemize
3867 Type may be one of: byte, sbyte, word, sword, hword, shword, dword, sdword,
3868 qword, sqword, float or double.
3871 \begin_layout Subsection
3872 memory.read_expr: Evaluate memory watch expression
3875 \begin_layout Itemize
3876 Syntax: string memory.read_expr(string expr)
3879 \begin_layout Standard
3880 Evaluate specified watch expression and return result
3883 \begin_layout Subsection
3884 memory.action: Run core action
3887 \begin_layout Itemize
3888 memory.action(string action, [<params>])
3891 \begin_layout Standard
3893 The different models expect parameters as:
3896 \begin_layout Itemize
3900 \begin_layout Itemize
3904 \begin_layout Itemize
3908 \begin_layout Itemize
3912 \begin_layout Itemize
3916 \begin_layout Subsection
3917 memory.get_lag_flag: Get lag flag
3920 \begin_layout Itemize
3921 Syntax: boolean memory.get_lag_flag()
3924 \begin_layout Standard
3925 Get the value of core lag flag.
3926 True if this frame has been lag so far, false if poll has been detected.
3929 \begin_layout Subsection
3930 memory.set_lag_flag: Set lag flag
3933 \begin_layout Itemize
3934 Syntax: none memory.set_lag_flag(boolean flag)
3937 \begin_layout Standard
3938 Set the value of core lag flag.
3939 This flag automatically gets cleared if poll is detected, but can be forcibly
3940 set or cleared if game so requires.
3943 \begin_layout Itemize
3944 Should only be used in on_frame_emulated callback.
3947 \begin_layout Itemize
3948 Setting or clearing this affects the emulator lag counter.
3951 \begin_layout Subsection
3952 memory.{,un}register{read,write,exec}: (Un)Register read / write / execute
3956 \begin_layout Itemize
3957 Syntax: function memory.registerread([string vma, ] number addr, function
3961 \begin_layout Itemize
3962 Syntax: function memory.registerwrite([string vma, ] number addr, function
3966 \begin_layout Itemize
3967 Syntax: function memory.registerexec([string vma, ] number addr, function
3971 \begin_layout Itemize
3972 Syntax: none memory.unregisterread([string vma, ] number addr, function fn);
3975 \begin_layout Itemize
3976 Syntax: none memory.unregisterwrite([string vma, ] number addr, function
3980 \begin_layout Itemize
3981 Syntax: none memory.unregisterexec([string vma, ] number addr, function fn);
3984 \begin_layout Standard
3985 Add or remove callback on memory read, write or execute (depending on the
3987 If <vma> is specified, <addr> is relative to it, otherwise <addr> is global.
3988 <fn> is the callback.
3989 The register* functions return <fn> (which can then be passed to unregister*
3993 \begin_layout Itemize
3994 Not all cores support this, and it may be unsupported for some VMAs.
3997 \begin_layout Itemize
3998 The functions are passed two parameters: Address and value.
4001 \begin_layout Subsection
4002 memory.{,un}registertrace: Set/Clear trace hook
4005 \begin_layout Itemize
4006 Syntax: function memory.registertrace(number processor, function fn);
4009 \begin_layout Itemize
4010 Syntax: none memory.unregistertrace(number processor, function fn);
4013 \begin_layout Standard
4014 Add or remove trace callback.
4015 <processor> is system-dependent processor number (0 is usually main CPU).
4016 The function arguments work like in other (un)register* functions.
4019 \begin_layout Itemize
4020 The functions are passed two parameters: Trace CPU and Trace event string.
4023 \begin_layout Subsection
4024 memory.cheat: Set cheat
4027 \begin_layout Itemize
4028 Syntax: none memory.cheat([string vma, ] number addr, number value);
4031 \begin_layout Itemize
4032 Syntax: none memory.cheat([string vma, ] number addr);
4035 \begin_layout Standard
4036 Set or clear cheat (value <value>) on address <addr>.
4037 If <vma> is specified, <addr> is relative to that.
4038 If <value> is not speicified, clear a cheat.
4041 \begin_layout Itemize
4042 Not all cores support this, and it may be unsupported for some VMAs.
4045 \begin_layout Subsection
4046 memory.setxmask: Set global execute hook mask
4049 \begin_layout Itemize
4050 Syntax: none memory.setxmask(number mask)
4053 \begin_layout Standard
4054 Set the global execute hook mask to <mask>.
4055 The meaning of each bit is system-dependent, but bit 0 should be the main
4059 \begin_layout Standard
4060 \begin_inset Newpage pagebreak
4066 \begin_layout Section
4070 \begin_layout Standard
4071 Contains newer memory functions.
4074 \begin_layout Subsection
4075 memory2(): Get all VMA names.
4078 \begin_layout Itemize
4079 Syntax: table memory2()
4082 \begin_layout Standard
4083 Returns array of all valid VMA names.
4086 \begin_layout Subsection
4087 memory2.<vma>:info: Get VMA info
4090 \begin_layout Itemize
4091 Syntax: table memory2.<vma>:info()
4094 \begin_layout Standard
4095 Return table describing given VMA.
4096 Includes fields address, size, last, readonly, special and endian.
4099 \begin_layout Subsection
4100 memory2.<vma>:<op>: Read/Write memory
4103 \begin_layout Itemize
4104 Syntax: none memory2.<vma>:<op>(number offset, number value)
4107 \begin_layout Itemize
4108 Syntax: number memory2.<vma>:<op>(number offset)
4111 \begin_layout Standard
4112 Read/Write value from/to given VMA <vma> at given offset <offset> (must
4114 The value written is <value>.
4115 <Op> is of form: [i][s]<type>, where:
4118 \begin_layout Itemize
4119 <type> is one of 'byte', 'word', 'hword', 'dword', 'qword', 'float', 'double'.
4122 \begin_layout Itemize
4123 'i' signifies that the value is treated as opposite-to-normal endianess,
4126 \begin_layout Itemize
4127 's' signifies that value is treated as signed (not available for floating-point).
4130 \begin_layout Subsection
4131 memory2.<vma>:read: Scatter-gather value read
4134 \begin_layout Itemize
4135 Syntax: number memory2.<vma>:read(number addr...)
4138 \begin_layout Standard
4139 Read value from given VMA <vma> at byte offsets <addr>..., given in order of
4140 increasing significance.
4141 Value of true and false are special.
4142 True increments address by 1, and false decrements address by 1.
4145 \begin_layout Subsection
4146 memory2.<vma>:sread: Signed scatter-gather value read
4149 \begin_layout Itemize
4150 Syntax: number memory2.<vma>:sread(number addr...)
4153 \begin_layout Standard
4154 Like memory2.<vma>:read, but reads signed values.
4157 \begin_layout Subsection
4158 memory2.<vma>:write: Scatter-gather value write
4161 \begin_layout Itemize
4162 Syntax: number memory2.<vma>:write(number val, number addr...)
4165 \begin_layout Standard
4166 Write value <val> to given VMA <vma> at byte offsets <addr>..., given in order
4167 of increasing significance.
4168 Value of true and false are special.
4169 True increments address by 1, and false decrements address by 1.
4172 \begin_layout Standard
4173 \begin_inset Newpage pagebreak
4179 \begin_layout Section
4183 \begin_layout Standard
4184 Contains random number generation methods.
4185 These functions do not return reproducable results.
4188 \begin_layout Subsection
4189 random.boolean: Random boolean
4192 \begin_layout Itemize
4193 Syntax: boolean random.boolean()
4196 \begin_layout Standard
4197 Returns true or false at random (50-50 chance).
4200 \begin_layout Subsection
4201 random.integer: Random integer
4204 \begin_layout Itemize
4205 Syntax: number random.integer(number highplusone)
4208 \begin_layout Itemize
4209 Syntax: number random.integer(number low, number high)
4212 \begin_layout Standard
4213 With one argument, return random integer [0,<highplusone>) (upper end exclusive).
4214 With two arguments, return random integer [<low>,<high>] (both ends inclusive).
4217 \begin_layout Standard
4218 The returned numbers are from uniform distribution.
4221 \begin_layout Subsection
4222 random.float: Random float
4225 \begin_layout Itemize
4226 Syntax: number random.float()
4229 \begin_layout Standard
4230 Returns random decimal number [0,1).
4233 \begin_layout Subsection
4234 random.among: Random parameter
4237 \begin_layout Itemize
4238 Syntax: value random.among(value values...)
4241 \begin_layout Standard
4242 Returns random parameter value, picked at uniform.
4243 Multiple equivalent values are returned with higher chance.
4246 \begin_layout Subsection
4247 random.amongtable: Random from table
4250 \begin_layout Itemize
4251 Syntax: value random.amongtable(table tab)
4254 \begin_layout Standard
4255 Returns random value from table <tab>.
4256 As in random.among, no equality testing is done.
4259 \begin_layout Standard
4260 \begin_inset Newpage pagebreak
4266 \begin_layout Section
4270 \begin_layout Subsection
4271 zip.create: Create a new zipfile
4274 \begin_layout Itemize
4275 Syntax: ZIPWRITER zip.create(string filename[, number compression])
4278 \begin_layout Standard
4279 Creates a new zipfile <filename>, with specified compression level <compression>
4283 \begin_layout Subsection
4284 zip.enumerate: Enumerate members in zipfile
4287 \begin_layout Itemize
4288 Syntax: Table zip.enumerate(string filename[, boolean invert])
4291 \begin_layout Standard
4292 Returns table of files in zip archive <filename>.
4293 If <invert> is true, instead of returning array of names, returns table
4294 with keys being member names and values being true.
4297 \begin_layout Subsection
4298 ZIPWRITER:commit: Finish creating ZIP file.
4301 \begin_layout Itemize
4302 Syntax: none ZIPWRITER:commit()
4305 \begin_layout Standard
4306 Closes the ZIP archive.
4307 Nothing more can be written.
4310 \begin_layout Subsection
4311 ZIPWRITER:rollback: Delete the ZIP file being creted
4314 \begin_layout Itemize
4315 Syntax: none ZIPWRITER:rollback()
4318 \begin_layout Standard
4319 Deletes the newly written ZIP archive.
4320 Nothing more can be written.
4323 \begin_layout Subsection
4324 ZIPWRITER:create_file: Start writing a new member
4327 \begin_layout Itemize
4328 Syntax: none ZIPWRITER:create_file(string filename)
4331 \begin_layout Standard
4332 Starts writing a new member <filename> in ZIP file.
4333 If member is open, it is closed.
4336 \begin_layout Subsection
4337 ZIPWRITER:close_file: Close member
4340 \begin_layout Itemize
4341 Syntax: none ZIPWRITER:close_file()
4344 \begin_layout Standard
4345 Closes member in ZIP file.
4348 \begin_layout Subsection
4349 ZIPWRITER:write: Write data
4352 \begin_layout Itemize
4353 Syntax none ZIPWRITER:write(string data)
4356 \begin_layout Standard
4357 Writes data <data> into ZIP file (binary mode).
4360 \begin_layout Standard
4361 \begin_inset Newpage pagebreak
4367 \begin_layout Section
4371 \begin_layout Standard
4372 Various callback-related functions.
4375 \begin_layout Subsection
4376 \begin_inset CommandInset label
4378 name "sub:callback.register:-Register-a"
4382 callback.register: Register a callback
4385 \begin_layout Itemize
4386 Syntax: function callback.register(string cbname, function cbfun);
4389 \begin_layout Standard
4390 Instruct function <cbfun> to be added to list of callbacks to call on event
4391 <cbname> (See section
4392 \begin_inset CommandInset ref
4394 reference "sec:Callbacks"
4399 The callback name does not have the 'on_' prefix (e.g.
4401 \begin_inset Quotes eld
4405 \begin_inset Quotes erd
4412 \begin_layout Subsection
4413 \begin_inset CommandInset label
4415 name "sub:callback.unregister:-Unregister-"
4419 callback.unregister: Unregister a callback
4422 \begin_layout Itemize
4423 Syntax: function callback.unregister(string cbname, function cbfun);
4426 \begin_layout Standard
4427 Instruct function <cbfun> to be removed from list of callbacks to call on
4431 \begin_layout Subsection
4432 callback.<cbname>:register: Register callback
4435 \begin_layout Itemize
4436 Syntax: function callback.<cbname>:register(function cbfun)
4439 \begin_layout Standard
4440 Synonym for callback.register (section
4441 \begin_inset CommandInset ref
4443 reference "sub:callback.register:-Register-a"
4447 ), albeit with callback name specified differently.
4450 \begin_layout Subsection
4451 callback.<cbname>:unregister: Register callback
4454 \begin_layout Itemize
4455 Syntax: function callback.<cbname>:unregister(function cbfun)
4458 \begin_layout Standard
4459 Synonym for callback.unregister (section
4460 \begin_inset CommandInset ref
4462 reference "sub:callback.unregister:-Unregister-"
4466 ), albeit with callback name specified differently.
4469 \begin_layout Section
4473 \begin_layout Standard
4474 Various bsnes-specific functions.
4477 \begin_layout Subsection
4478 bsnes.dump_sprite: Dump a sprite
4481 \begin_layout Itemize
4482 Syntax: BITMAP bsnes.dump_sprite([string vma, ] number addr, number width,
4483 number height[, number stride])
4486 \begin_layout Standard
4487 Dumps given sprite (in native format) from memory.
4489 \begin_inset Quotes eld
4493 \begin_inset Quotes erd
4497 <Width> and <height> are given in 8x8 blocks.
4498 <Stride> overrides row stride (default 512).
4501 \begin_layout Subsection
4502 bsnes.dump_palette: Dump a palette
4505 \begin_layout Itemize
4506 Syntax: PALETTE bsnes.dump_palette([string vma, ] number addr, bool full256,
4510 \begin_layout Standard
4511 Dumps a palette from memory.
4513 \begin_inset Quotes eld
4517 \begin_inset Quotes erd
4521 If <full256> is true, 256 colors are dumped (otherwise 16).
4522 If <first_trans> is true, first color is forced transparent.
4525 \begin_layout Section
4529 \begin_layout Standard
4530 Contains copy of global variables from time of Lua initialization.
4534 \begin_layout Standard
4535 \begin_inset Newpage pagebreak
4541 \begin_layout Section
4542 \begin_inset CommandInset label
4544 name "sec:Callbacks"
4551 \begin_layout Standard
4552 Various callbacks to Lua that can occur.
4555 \begin_layout Subsection
4556 on_paint: Screen is being painted
4559 \begin_layout Itemize
4560 Callback: on_paint(bool not_synth)
4563 \begin_layout Standard
4564 Called when screen is being painted.
4565 Any gui.* calls requiring graphic context draw on the screen.
4568 \begin_layout Itemize
4569 not_synth is true if this hook is being called in response to received frame,
4573 \begin_layout Subsection
4574 on_video: Dumped video frame is being painted
4577 \begin_layout Itemize
4578 Callback: on_video()
4581 \begin_layout Standard
4582 Called when video dump frame is being painted.
4583 Any gui.* calls requiring graphic context draw on the video.
4586 \begin_layout Subsection
4587 on_frame_emulated: Frame emulation complete
4590 \begin_layout Itemize
4591 Callback: on_frame_emulated()
4594 \begin_layout Standard
4595 Called when emulating frame has completed and on_paint()/on_video() calls
4596 are about to be issued.
4599 \begin_layout Subsection
4600 on_frame: Frame emulation starting.
4603 \begin_layout Itemize
4604 Callback: on_frame()
4607 \begin_layout Standard
4608 Called on each starting whole frame.
4611 \begin_layout Subsection
4612 on_startup: Emulator startup complete
4615 \begin_layout Itemize
4616 Callback: on_startup()
4619 \begin_layout Standard
4620 Called when the emulator is starting (lsnes.rc and --run files has been run).
4623 \begin_layout Subsection
4624 on_rewind: Movie rewound to beginning
4627 \begin_layout Itemize
4628 Callback: on_rewind()
4631 \begin_layout Standard
4632 Called when rewind movie to beginning has completed.
4635 \begin_layout Subsection
4636 on_pre_load: Load operation is about to start
4639 \begin_layout Itemize
4640 Callback: on_pre_load(string name)
4643 \begin_layout Standard
4644 Called just before savestate/movie load occurs (note: loads are always delayed,
4645 so this occurs even when load was initiated by lua).
4648 \begin_layout Subsection
4649 on_err_Load: Load failed
4652 \begin_layout Itemize
4653 Callback: on_err_load(string name)
4656 \begin_layout Standard
4657 Called if loadstate goes wrong.
4660 \begin_layout Subsection
4661 on_post_load: Load completed
4664 \begin_layout Itemize
4665 Callback: on_post_load(string name, boolean was_savestate)
4668 \begin_layout Standard
4669 Called on successful loadstate.
4670 was_savestate gives if this was a savestate or a movie.
4673 \begin_layout Subsection
4674 on_pre_save: Save operation is about to start
4677 \begin_layout Itemize
4678 Callback: on_pre_save(string name, boolean is_savestate)
4681 \begin_layout Standard
4682 Called just before savestate save occurs (note: movie saves are synchronous
4683 and won't trigger these callbacks if called from Lua).
4686 \begin_layout Subsection
4687 on_err_save: Save failed
4690 \begin_layout Itemize
4691 Callback: on_err_save(string name)
4694 \begin_layout Standard
4695 Called if savestate goes wrong.
4698 \begin_layout Subsection
4699 on_post_save: Save completed
4702 \begin_layout Itemize
4703 Callback: on_post_save(string name, boolean is_savestate)
4706 \begin_layout Standard
4707 Called on successful savaestate.
4708 is_savestate gives if this was a savestate or a movie.
4711 \begin_layout Subsection
4712 on_quit: Emulator is shutting down
4715 \begin_layout Itemize
4719 \begin_layout Standard
4720 Called when emulator is shutting down.
4723 \begin_layout Subsection
4724 on_input: Polling for input
4727 \begin_layout Standard
4728 Called when emulator is just sending input to bsnes core.
4729 Warning: This is called even in readonly mode, but the results are ignored.
4732 \begin_layout Subsection
4733 on_reset: System has been reset
4736 \begin_layout Itemize
4737 Callback: on_reset()
4740 \begin_layout Standard
4741 Called when system is reset.
4744 \begin_layout Subsection
4745 on_readwrite: Entered readwrite mode
4748 \begin_layout Itemize
4749 Callback: on_readwrite()
4752 \begin_layout Standard
4753 Called when moving into readwrite mode as result of
4754 \begin_inset Quotes eld
4758 \begin_inset Quotes erd
4761 command (note: moving to rwmode by Lua won't trigger this, as per recursive
4765 \begin_layout Subsection
4766 on_snoop/on_snoop2: Snoop core controller reads
4769 \begin_layout Itemize
4770 Callback: on_snoop(number port, number controller, number index, number
4774 \begin_layout Itemize
4775 Callback: on_snoop2(number port, number controller, number index, number
4779 \begin_layout Standard
4780 Called each time bsnes asks for input.
4781 The value is the final value to be sent to bsnes core (readonly mode, autohold
4782 and autofire have been taken into account).
4783 Might be useful when translating movies to format suitable for console
4785 Note: There is no way to modify the value to be sent.
4788 \begin_layout Itemize
4789 On_snoop2 is called instead of on_snoop if defined.
4790 Reserves port 0 for system, having first user port be port 1.
4793 \begin_layout Subsection
4794 on_keyhook: Hooked key/axis has been moved
4797 \begin_layout Itemize
4798 Callback: on_keyhook(string keyname, table state)
4801 \begin_layout Standard
4802 Sent when key that has keyhook events requested changes state.
4803 Keyname is name of the key (group) and state is the state (same kind as
4804 table values in input.raw).
4807 \begin_layout Subsection
4811 \begin_layout Itemize
4815 \begin_layout Standard
4816 Called when requested by set_idle_timeout(), the timeout has expired and
4817 emulator is waiting.
4820 \begin_layout Subsection
4821 on_timer: Timer event
4824 \begin_layout Itemize
4825 Callback: on_timer()
4828 \begin_layout Standard
4829 Called when requested by set_idle_timeout() and the timeout has expired
4830 (regardless if emulator is waiting).
4833 \begin_layout Subsection
4834 on_set_rewind: Rewind point has been set
4837 \begin_layout Itemize
4838 Callback: on_set_rewind(UNSAFEREWIND r)
4841 \begin_layout Standard
4842 Called when unsafe rewind object has been constructed.
4845 \begin_layout Subsection
4846 on_pre_rewind: Rewind is about to occur
4849 \begin_layout Itemize
4850 Callback: on_pre_rewind()
4853 \begin_layout Standard
4854 Called just before unsafe rewind is about to occur.
4857 \begin_layout Subsection
4858 on_post_rewind: Rewind has occured
4861 \begin_layout Itemize
4862 Callback: on_post_rewind()
4865 \begin_layout Standard
4866 Called just after unsafe rewind has occured.
4869 \begin_layout Subsection
4870 on_button: Button has been pressed
4873 \begin_layout Itemize
4874 Callback: on_button(number port, number controller, number index, string
4878 \begin_layout Standard
4879 Called on controller button press, with following parameters:
4882 \begin_layout Itemize
4883 port: Port number (0 is system)
4886 \begin_layout Itemize
4887 controller: Controller within port
4890 \begin_layout Itemize
4891 index: Index of button.
4894 \begin_layout Itemize
4895 type: Type of event, one of:
4899 \begin_layout Itemize
4900 \begin_inset Quotes eld
4904 \begin_inset Quotes erd
4907 : Button was pressed.
4910 \begin_layout Itemize
4911 \begin_inset Quotes eld
4915 \begin_inset Quotes erd
4918 : Button was released.
4921 \begin_layout Itemize
4922 \begin_inset Quotes eld
4926 \begin_inset Quotes erd
4932 \begin_layout Itemize
4933 \begin_inset Quotes eld
4937 \begin_inset Quotes erd
4940 : Released from hold.
4943 \begin_layout Itemize
4944 \begin_inset Quotes eld
4948 \begin_inset Quotes erd
4951 : Typing input on button.
4954 \begin_layout Itemize
4955 \begin_inset Quotes eld
4959 \begin_inset Quotes erd
4962 : Typing input undone.
4965 \begin_layout Itemize
4966 \begin_inset Quotes eld
4969 autofire <duty> <cycle>
4970 \begin_inset Quotes erd
4973 : Autofire with specifie duty and cycle.
4976 \begin_layout Itemize
4977 \begin_inset Quotes eld
4981 \begin_inset Quotes erd
4987 \begin_layout Itemize
4988 \begin_inset Quotes eld
4992 \begin_inset Quotes erd
4995 : Analog action on axis.
4999 \begin_layout Subsection
5000 on_movie_lost: Movie data is about to be lost
5003 \begin_layout Itemize
5004 Callback: on_movie_lost(STRING kind)
5007 \begin_layout Standard
5008 Called just before something would happen that could lose movie data.
5012 \begin_layout Itemize
5013 readwrite: Switching to readwrite mode.
5016 \begin_layout Itemize
5017 reload: ROM is being reloaded in readwrite mode.
5020 \begin_layout Itemize
5021 load: New movie is being loaded.
5024 \begin_layout Itemize
5025 unsaferewind: Unsafe rewind is happening.
5028 \begin_layout Subsection
5029 on_latch: Latch line is rising
5032 \begin_layout Itemize
5033 Callback: on_latch(<core-dependent-parameters>)
5036 \begin_layout Standard
5037 Called when latch line for controller is rising.
5038 Some cores may not support this.
5041 \begin_layout Section
5042 System-dependent behaviour
5045 \begin_layout Subsection
5049 \begin_layout Itemize
5050 Registers are: pbpc, pb, pc, r0, r1, r2, r3, r4, r5, a, x, y, z, s, d, db,
5051 p, e, irq, wai, mdr, vector, aa, rd, sp, dp, p_n, p_v, p_m, p_x, p_d, p_i,
5052 p_z, p_c, ppu_display_disabled, ppu_oam_priority, ppu_bg_tilesize[0], ppu_bg_ti
5053 lesize[1], ppu_bg_tilesize[2], ppu_bg_tilesize[3], ppu_bg3_priority, ppu_mosaic_
5054 enabled[0], ppu_mosaic_enabled[1], ppu_mosaic_enabled[2], ppu_mosaic_enabled[3],
5055 ppu_vram_incmode, ppu_mode7_vflip, ppu_mode7_hflip, ppu_window1_enabled[0],
5056 ppu_window1_enabled[1], ppu_window1_enabled[2], ppu_window1_enabled[3],
5057 ppu_window1_enabled[4], ppu_window1_enabled[5], ppu_window1_invert[0],
5058 ppu_window1_invert[1], ppu_window1_invert[2], ppu_window1_invert[3], ppu_window
5059 1_invert[4], ppu_window1_invert[5], ppu_window2_enabled[0], ppu_window2_enabled[
5060 1], ppu_window2_enabled[2], ppu_window2_enabled[3], ppu_window2_enabled[4],
5061 ppu_window2_enabled[5], ppu_window2_invert[0], ppu_window2_invert[1], ppu_windo
5062 w2_invert[2], ppu_window2_invert[3], ppu_window2_invert[4], ppu_window2_invert[5
5063 ], ppu_bg_enabled[0], ppu_bg_enabled[1], ppu_bg_enabled[2], ppu_bg_enabled[3],
5064 ppu_bg_enabled[4], ppu_bgsub_enabled[0], ppu_bgsub_enabled[1], ppu_bgsub_enable
5065 d[2], ppu_bgsub_enabled[3], ppu_bgsub_enabled[4], ppu_window_enabled[0],
5066 ppu_window_enabled[1], ppu_window_enabled[2], ppu_window_enabled[3], ppu_window
5067 _enabled[4], ppu_sub_window_enabled[0], ppu_sub_window_enabled[1], ppu_sub_windo
5068 w_enabled[2], ppu_sub_window_enabled[3], ppu_sub_window_enabled[4], ppu_addsub_m
5069 ode, ppu_direct_color, ppu_color_mode, ppu_color_halve, ppu_color_enabled[0],
5070 ppu_color_enabled[1], ppu_color_enabled[2], ppu_color_enabled[3], ppu_color_ena
5071 bled[4], ppu_color_enabled[5], ppu_mode7_extbg, ppu_pseudo_hires, ppu_overscan,
5072 ppu_oam_interlace, ppu_interlace, ppu_latch_hcounter, ppu_latch_vcounter,
5073 ppu_counters_latched, ppu_time_over, ppu_range_over, ppu_ppu1_mdr, ppu_ppu2_mdr
5074 , ppu_bg_y[0], ppu_bg_y[1], ppu_bg_y[2], ppu_bg_y[3], ppu_ioamaddr, ppu_icgramad
5075 dr, ppu_display_brightness, ppu_oam_basesize, ppu_oam_nameselect, ppu_oam_tdaddr
5076 , ppu_oam_baseaddr, ppu_oam_addr, ppu_oam_firstsprite, ppu_oam_latchdata,
5077 ppu_bg_mode, ppu_mosaic_size, ppu_mosaic_countdown, ppu_bg_scaddr[0], ppu_bg_sc
5078 addr[1], ppu_bg_scaddr[2], ppu_bg_scaddr[3], ppu_bg_scsize[0], ppu_bg_scsize[1],
5079 ppu_bg_scsize[2], ppu_bg_scsize[3], ppu_bg_tdaddr[0], ppu_bg_tdaddr[1],
5080 ppu_bg_tdaddr[2], ppu_bg_tdaddr[3], ppu_bg_ofslatch, ppu_m7_hofs, ppu_m7_vofs,
5081 ppu_bg_hofs[0], ppu_bg_hofs[1], ppu_bg_hofs[2], ppu_bg_hofs[3], ppu_bg_vofs[0],
5082 ppu_bg_vofs[1], ppu_bg_vofs[2], ppu_bg_vofs[3], ppu_vram_mapping, ppu_vram_incs
5083 ize, ppu_vram_addr, ppu_mode7_repeat, ppu_m7_latch, ppu_m7a, ppu_m7b, ppu_m7c,
5084 ppu_m7d, ppu_m7x, ppu_m7y, ppu_cgram_addr, ppu_cgram_latchdata, ppu_window1_lef
5085 t, ppu_window1_right, ppu_window2_left, ppu_window2_right, ppu_window_mask[0],
5086 ppu_window_mask[1], ppu_window_mask[2], ppu_window_mask[3], ppu_window_mask[4],
5087 ppu_window_mask[5], ppu_color_mask, ppu_colorsub_mask, ppu_color_r, ppu_color_g
5088 , ppu_color_b, ppu_color_rgb, ppu_scanlines, ppu_hcounter, ppu_vcounter,
5089 ppu_vram_readbuffer, ppu_oam_itemcount, ppu_oam_tilecount,
5092 \begin_layout Itemize
5093 on_latch has no parameters
5096 \begin_layout Itemize
5097 CPU 0 is S-CPU, 1 is S-SMP.
5100 \begin_layout Itemize
5101 Cheats are supported for ROM, SRAM, WRAM, BSXFLASH, SLOT{A,B}_{RAM,ROM}.
5104 \begin_layout Itemize
5105 Read/Write/Execute hooks are supported for ROM, SRAM, WRAM, BSXFLASH, SLOT{A,B}_
5109 \begin_layout Subsection
5113 \begin_layout Itemize
5114 Registers are: wrambank, cyclecounter, pc, sp, hf1, hf2, zf, cf, a, b, c,
5118 \begin_layout Itemize
5119 on_latch is not supported
5122 \begin_layout Itemize
5126 \begin_layout Itemize
5127 Cheats are supported for ROM, SRAM and WRAM.
5130 \begin_layout Itemize
5131 Read/Write/Execute hooks are supported for ROM (read/execute only), SRAM