1 #LyX 2.1 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
16 \font_default_family default
17 \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
41 \use_package amsmath 1
42 \use_package amssymb 1
45 \use_package mathdots 1
46 \use_package mathtools 1
48 \use_package stackrel 1
49 \use_package stmaryrd 1
50 \use_package undertilde 1
52 \cite_engine_type default
56 \paperorientation portrait
73 \paragraph_separation indent
74 \paragraph_indentation default
75 \quotes_language english
78 \paperpagestyle default
79 \tracking_changes false
89 lsnes Lua functions reference
96 \begin_layout Standard
97 \begin_inset CommandInset toc
98 LatexCommand tableofcontents
105 \begin_layout Standard
106 \begin_inset Newpage pagebreak
112 \begin_layout Section
116 \begin_layout Subsection
120 \begin_layout Itemize
121 Coordinates increase to right and down.
124 \begin_layout Itemize
125 The origin is at top left of game area or buffer.
128 \begin_layout Subsection
132 \begin_layout Itemize
133 Methods that draw something (unless stated otherwise) require a valid rendering
135 This context can come in three ways:
139 \begin_layout Enumerate
140 The default rendering context of paint callback (the screen).
143 \begin_layout Enumerate
144 The default rendering context of video callback (the video).
147 \begin_layout Enumerate
148 Explicitly set rendering context (RENDERCTX:set).
152 \begin_layout Itemize
153 The rendering context is always reset when callback ends.
156 \begin_layout Subsection
160 \begin_layout Standard
161 (Direct) colors can be specified either as numbers or strings.
164 \begin_layout Itemize
165 -1 is fully transparent.
168 \begin_layout Itemize
169 Non-negative numbers less than
170 \begin_inset Formula $2^{32}$
173 are partially opaque colors (
174 \begin_inset Formula $a*2^{24}+r*2^{16}+g*2^{8}+b$
181 \begin_layout Itemize
182 \begin_inset Formula $a$
186 \begin_inset Formula $0-255$
190 \begin_inset Formula $0$
194 \begin_inset Formula $256$
197 would be fully transparent.
201 \begin_layout Itemize
202 Thus, numbers in range
203 \begin_inset Formula $0-16777215$
206 stand for fully opaque colors.
210 \begin_layout Itemize
211 \begin_inset Formula $r$
215 \begin_inset Formula $g$
219 \begin_inset Formula $b$
222 are intensities of base colors on scale
223 \begin_inset Formula $0-255$
230 \begin_layout Itemize
231 Color can also be specified by name as string: The following color names
232 are known: aliceblue antiquewhite antiquewhite1 antiquewhite2 antiquewhite3
233 antiquewhite4 aqua aquamarine aquamarine1 aquamarine2 aquamarine3 aquamarine4
234 azure azure1 azure2 azure3 azure4 beige bisque bisque1 bisque2 bisque3
235 bisque4 black blanchedalmond blue blue1 blue2 blue3 blue4 blueviolet brown
236 brown1 brown2 brown3 brown4 burlywood burlywood1 burlywood2 burlywood3
237 burlywood4 cadet cadetblue cadetblue1 cadetblue2 cadetblue3 cadetblue4
238 chartreuse chartreuse1 chartreuse2 chartreuse3 chartreuse4 chocolate chocolate1
239 chocolate2 chocolate3 chocolate4 coral coral1 coral2 coral3 coral4 cornflowerbl
240 ue cornsilk cornsilk1 cornsilk2 cornsilk3 cornsilk4 crimson cyan cyan1 cyan2
241 cyan3 cyan4 darkblue darkcyan darkgoldenrod darkgoldenrod1 darkgoldenrod2
242 darkgoldenrod3 darkgoldenrod4 darkgray darkgreen darkgrey darkkhaki darkmagenta
243 darkolivegreen darkolivegreen1 darkolivegreen2 darkolivegreen3 darkolivegreen4
244 darkorange darkorange1 darkorange2 darkorange3 darkorange4 darkorchid darkorchi
245 d1 darkorchid2 darkorchid3 darkorchid4 darkred darksalmon darkseagreen darkseagr
246 een1 darkseagreen2 darkseagreen3 darkseagreen4 darkslateblue darkslategray
247 darkslategray1 darkslategray2 darkslategray3 darkslategray4 darkslategrey
248 darkturquoise darkviolet deeppink deeppink1 deeppink2 deeppink3 deeppink4
249 deepskyblue deepskyblue1 deepskyblue2 deepskyblue3 deepskyblue4 dimgray
250 dimgrey dodgerblue dodgerblue1 dodgerblue2 dodgerblue3 dodgerblue4 firebrick
251 firebrick1 firebrick2 firebrick3 firebrick4 floralwhite forestgreen fractal
252 fuchsia gainsboro ghostwhite gold gold1 gold2 gold3 gold4 goldenrod goldenrod1
253 goldenrod2 goldenrod3 goldenrod4 gray gray0 gray1 gray10 gray100 gray11
254 gray12 gray13 gray14 gray15 gray16 gray17 gray18 gray19 gray2 gray20 gray21
255 gray22 gray23 gray24 gray25 gray26 gray27 gray28 gray29 gray3 gray30 gray31
256 gray32 gray33 gray34 gray35 gray36 gray37 gray38 gray39 gray4 gray40 gray41
257 gray42 gray43 gray44 gray45 gray46 gray47 gray48 gray49 gray5 gray50 gray51
258 gray52 gray53 gray54 gray55 gray56 gray57 gray58 gray59 gray6 gray60 gray61
259 gray62 gray63 gray64 gray65 gray66 gray67 gray68 gray69 gray7 gray70 gray71
260 gray72 gray73 gray74 gray75 gray76 gray77 gray78 gray79 gray8 gray80 gray81
261 gray82 gray83 gray84 gray85 gray86 gray87 gray88 gray89 gray9 gray90 gray91
262 gray92 gray93 gray94 gray95 gray96 gray97 gray98 gray99 green green1 green2
263 green3 green4 greenyellow grey grey0 grey1 grey10 grey100 grey11 grey12
264 grey13 grey14 grey15 grey16 grey17 grey18 grey19 grey2 grey20 grey21 grey22
265 grey23 grey24 grey25 grey26 grey27 grey28 grey29 grey3 grey30 grey31 grey32
266 grey33 grey34 grey35 grey36 grey37 grey38 grey39 grey4 grey40 grey41 grey42
267 grey43 grey44 grey45 grey46 grey47 grey48 grey49 grey5 grey50 grey51 grey52
268 grey53 grey54 grey55 grey56 grey57 grey58 grey59 grey6 grey60 grey61 grey62
269 grey63 grey64 grey65 grey66 grey67 grey68 grey69 grey7 grey70 grey71 grey72
270 grey73 grey74 grey75 grey76 grey77 grey78 grey79 grey8 grey80 grey81 grey82
271 grey83 grey84 grey85 grey86 grey87 grey88 grey89 grey9 grey90 grey91 grey92
272 grey93 grey94 grey95 grey96 grey97 grey98 grey99 honeydew honeydew1 honeydew2
273 honeydew3 honeydew4 hotpink hotpink1 hotpink2 hotpink3 hotpink4 indianred
274 indianred1 indianred2 indianred3 indianred4 indigo ivory ivory1 ivory2
275 ivory3 ivory4 khaki khaki1 khaki2 khaki3 khaki4 lavender lavenderblush
276 lavenderblush1 lavenderblush2 lavenderblush3 lavenderblush4 lawngreen lemonchif
277 fon lemonchiffon1 lemonchiffon2 lemonchiffon3 lemonchiffon4 lightblue lightblue1
278 lightblue2 lightblue3 lightblue4 lightcoral lightcyan lightcyan1 lightcyan2
279 lightcyan3 lightcyan4 lightgoldenrod lightgoldenrod1 lightgoldenrod2 lightgolde
280 nrod3 lightgoldenrod4 lightgoldenrodyellow lightgray lightgreen lightgrey
281 lightpink lightpink1 lightpink2 lightpink3 lightpink4 lightsalmon lightsalmon1
282 lightsalmon2 lightsalmon3 lightsalmon4 lightseagreen lightskyblue lightskyblue1
283 lightskyblue2 lightskyblue3 lightskyblue4 lightslateblue lightslategray
284 lightslategrey lightsteelblue lightsteelblue1 lightsteelblue2 lightsteelblue3
285 lightsteelblue4 lightyellow lightyellow1 lightyellow2 lightyellow3 lightyellow4
286 lime limegreen linen magenta magenta1 magenta2 magenta3 magenta4 maroon
287 maroon1 maroon2 maroon3 maroon4 mediumaquamarine mediumblue mediumforestgreen
288 mediumgoldenrod mediumorchid mediumorchid1 mediumorchid2 mediumorchid3
289 mediumorchid4 mediumpurple mediumpurple1 mediumpurple2 mediumpurple3 mediumpurp
290 le4 mediumseagreen mediumslateblue mediumspringgreen mediumturquoise mediumviole
291 tred midnightblue mintcream mistyrose mistyrose1 mistyrose2 mistyrose3 mistyrose
292 4 moccasin navajowhite navajowhite1 navajowhite2 navajowhite3 navajowhite4
293 navy navyblue oldlace olive olivedrab olivedrab1 olivedrab2 olivedrab3
294 olivedrab4 orange orange1 orange2 orange3 orange4 orangered orangered1
295 orangered2 orangered3 orangered4 orchid orchid1 orchid2 orchid3 orchid4
296 palegoldenrod palegreen palegreen1 palegreen2 palegreen3 palegreen4 paleturquoi
297 se paleturquoise1 paleturquoise2 paleturquoise3 paleturquoise4 palevioletred
298 palevioletred1 palevioletred2 palevioletred3 palevioletred4 papayawhip
299 peachpuff peachpuff1 peachpuff2 peachpuff3 peachpuff4 peru pink pink1 pink2
300 pink3 pink4 plum plum1 plum2 plum3 plum4 powderblue purple purple1 purple2
301 purple3 purple4 red red1 red2 red3 red4 rosybrown rosybrown1 rosybrown2
302 rosybrown3 rosybrown4 royalblue royalblue1 royalblue2 royalblue3 royalblue4
303 saddlebrown salmon salmon1 salmon2 salmon3 salmon4 sandybrown seagreen
304 seagreen1 seagreen2 seagreen3 seagreen4 seashell seashell1 seashell2 seashell3
305 seashell4 sienna sienna1 sienna2 sienna3 sienna4 silver skyblue skyblue1
306 skyblue2 skyblue3 skyblue4 slateblue slateblue1 slateblue2 slateblue3 slateblue
307 4 slategray slategray1 slategray2 slategray3 slategray4 slategrey snow snow1
308 snow2 snow3 snow4 springgreen springgreen1 springgreen2 springgreen3 springgree
309 n4 steelblue steelblue1 steelblue2 steelblue3 steelblue4 tan tan1 tan2 tan3
310 tan4 teal thistle thistle1 thistle2 thistle3 thistle4 tomato tomato1 tomato2
311 tomato3 tomato4 transparent turquoise turquoise1 turquoise2 turquoise3
312 turquoise4 violet violetred violetred1 violetred2 violetred3 violetred4
313 wheat wheat1 wheat2 wheat3 wheat4 white whitesmoke yellow yellow1 yellow2
314 yellow3 yellow4 yellowgreen
317 \begin_layout Itemize
318 The HSL base color names: hsl-<hue><saturation><lightness>.
322 \begin_layout Itemize
323 Hue can be one of: r (red), ry (red-yellow), o (orange, same as red-yellow),
324 y (yellow), yg (yellow-green), g (green), gc (green-cyan), c (cyan), cb
325 (cyan-blue), b (blue), bm (blue-magenta), m (magenta), mr (magenta-red).
328 \begin_layout Itemize
329 Saturation is 0-8, where 0 is greyscale and 8 is fully saturated.
332 \begin_layout Itemize
333 Lightness is 0-8, where 0 is black and 8 is white.
337 \begin_layout Itemize
338 The color names can have a modifier after space (multiple modifiers are
339 allowed, separated by spaces): opaque10, opaque20, opaque25, opaque30,
340 opaque40, opaque50, opaque60, opaque70, opaque75, opaque80, opaque90, opaque,
341 hue{+,-}{1-23}, {saturation,lightness}{+,-}{1-16}.
345 \begin_layout Itemize
346 opaqueness is measured as percentage.
349 \begin_layout Itemize
350 Hue adjustments are on 24-step scale.
353 \begin_layout Itemize
354 Saturation and lightness adjustments are on 16-step scale.
358 \begin_layout Section
362 \begin_layout Standard
363 These tokens are special, and are expanded while the script is being loaded
366 \begin_layout Subsection
367 @@LUA_SCRIPT_FILENAME@@
370 \begin_layout Standard
371 Expanded to string token containing path and filename of this Lua script.
372 Handy for referencing other lua scripts or resources that are relative
376 \begin_layout Standard
377 In practicular, this is suitable to be passed as base argument of various
378 functions like loadfile, dofile, resolve_filename, gui.bitmap_load, gui.bitmap_lo
379 ad_png and gui.bitmap_load_pal.
382 \begin_layout Section
386 \begin_layout Subsection
387 MMAP_STRUCT: Quasi-table mapping emulated memory
390 \begin_layout Standard
391 Objects of this class act like tables, except that the values are reflected
392 to and from emulated memory.
395 \begin_layout Subsubsection
396 static function new: Create new instance
399 \begin_layout Itemize
400 Syntax: mmap memory.mmap.new()
403 \begin_layout Itemize
404 Syntax: mmap classes.MMAP_STRUCT.new()
407 \begin_layout Itemize
408 Deprecated: mmap memory.map_structure()
411 \begin_layout Standard
415 \begin_layout Itemize
416 mmap: MMAP_STRUCT: The created mmap structure.
419 \begin_layout Standard
420 Create a new MMAP_STRUCT (with no mappings) and return it.
423 \begin_layout Subsubsection
424 operator(): Bind key in mmap structure
427 \begin_layout Itemize
428 Syntax: obj(key, {marea, address|addrobj}, type)
431 \begin_layout Standard
435 \begin_layout Itemize
436 obj: MMAP_STRUCT: The structure to manipulate.
439 \begin_layout Itemize
440 key: String: The name of the key in array to map.
443 \begin_layout Itemize
444 marea: String: The memory area the mapped address is in (default: global
448 \begin_layout Itemize
449 address: Number: The offset of memory addreess, relative to specified memory
450 area or global memory space.
453 \begin_layout Itemize
454 addrobj: ADDRESS: The memory address.
457 \begin_layout Itemize
458 type: String: The type of data to map.
462 \begin_layout Itemize
463 One of: byte, sbyte, word, sword, hword, shword, dword, sdword, qword, sqword,
468 \begin_layout Standard
469 Bind key <key> in mmap structure <obj> to address <address> (relative to
471 The memory address is treated as type <type>.
474 \begin_layout Itemize
476 \begin_inset Quotes eld
480 \begin_inset Quotes erd
484 \begin_inset Quotes eld
488 \begin_inset Quotes erd
492 \begin_inset Quotes eld
496 \begin_inset Quotes erd
502 \begin_layout Standard
503 This binds signed word at address WRAM+0x2A into key
504 \begin_inset Quotes eld
508 \begin_inset Quotes erd
514 \begin_layout Standard
515 \begin_inset Newpage pagebreak
521 \begin_layout Subsection
522 ZIPWRITER: Write .zip files
525 \begin_layout Standard
526 This class does writing of .zip files.
529 \begin_layout Subsubsection
530 Static function new: Create a new zipfile
533 \begin_layout Itemize
534 Syntax: zip zip.writer.new(filename, [compression])
537 \begin_layout Itemize
538 Deprecated: zip zip.create(filename, [compression])
541 \begin_layout Standard
545 \begin_layout Itemize
546 filename: string: The name of the file to write.
549 \begin_layout Itemize
550 compression: number: Compression level (0-9).
554 \begin_layout Standard
558 \begin_layout Itemize
559 zip: ZIPWRITER: The newly created ZIP writer.
562 \begin_layout Standard
563 Create a new ZIPWRITER object and return it.
566 \begin_layout Subsubsection
567 Method commit: Finish creating ZIP file.
570 \begin_layout Itemize
571 Syntax: zipfile:commit()
574 \begin_layout Standard
578 \begin_layout Itemize
579 zipfile: ZIPFILE: The ZIP file object.
582 \begin_layout Standard
583 Finish writing the ZIP file and actually create it on disk.
586 \begin_layout Itemize
587 If a member is currently open, it is implicitly closed.
590 \begin_layout Itemize
591 Invoking this on already committed or rolled back zipfile causes an error.
594 \begin_layout Subsubsection
595 Method rollback: Cancel writing the ZIP file.
598 \begin_layout Itemize
599 Syntax: zipfile:rollback()
602 \begin_layout Standard
606 \begin_layout Itemize
607 zipfile: ZIPFILE: The ZIP file object.
610 \begin_layout Standard
611 Cancel writing the whole ZIP file.
612 The file on disk will not be modified.
615 \begin_layout Itemize
616 If a member is currently open, it is implicitly closed.
619 \begin_layout Itemize
620 Invoking this on already committed or rolled back zipfile causes an error.
623 \begin_layout Subsubsection
624 Method create_file: Start writing a new member
627 \begin_layout Itemize
628 Syntax: zipfile:create_file(filename)
631 \begin_layout Standard
635 \begin_layout Itemize
636 zipfile: ZIPFILE: The ZIP file object.
639 \begin_layout Itemize
640 string filename: Name of the new member to create
643 \begin_layout Standard
644 Start writing a new member <filename> in ZIP file.
647 \begin_layout Itemize
648 If a member is currently open, it is implicitly closed.
651 \begin_layout Itemize
652 Invoking this on already committed or rolled back zipfile causes an error.
655 \begin_layout Subsubsection
656 Method close_file: Close member
659 \begin_layout Itemize
660 Syntax: zipfile:close_file()
663 \begin_layout Standard
667 \begin_layout Itemize
668 zipfile: ZIPFILE: The ZIP file object.
671 \begin_layout Standard
672 Close the currently open member in zipfile.
675 \begin_layout Itemize
676 Invoking this on already committed or rolled back zipfile causes an error.
679 \begin_layout Itemize
680 Invoking this without an open member causes an error.
683 \begin_layout Subsubsection
684 Method write: Write data
687 \begin_layout Itemize
688 Syntax: zipfile:write(data)
691 \begin_layout Standard
695 \begin_layout Itemize
696 zipfile: ZIPFILE: The ZIP file object.
699 \begin_layout Itemize
700 data: string: The data to write.
703 \begin_layout Standard
704 Write <data> in binary mode (as-is) to currently open member.
707 \begin_layout Itemize
708 Invoking this without a member being open causes an error.
711 \begin_layout Standard
712 \begin_inset Newpage pagebreak
718 \begin_layout Subsection
719 TILEMAP: Tiled collection of bitmaps.
722 \begin_layout Standard
723 A tilemap is tiled table, each cell holding a bitmap (indexed or direct).
726 \begin_layout Subsubsection
727 Static function new: Create a tilemap
730 \begin_layout Itemize
731 Syntax: tilemap gui.tiled_bitmap.new(w, h, bw, bh);
734 \begin_layout Itemize
735 Syntax: tilemap classes.TILEMAP.new(w, h, bw, bh);
738 \begin_layout Itemize
739 Deprecated: tilemap gui.tilemap(w, h, bw, bh);
742 \begin_layout Standard
746 \begin_layout Itemize
747 w: number: Width of the tilemap in tiles
750 \begin_layout Itemize
751 h: number: Height of the tilemap in tiles
754 \begin_layout Itemize
755 bw: number: Width of each tile in pixels.
758 \begin_layout Itemize
759 bh: number: Height of each tile in pixels.
762 \begin_layout Standard
766 \begin_layout Itemize
767 tilemap: TILEMAP: the newly created tilemap
770 \begin_layout Standard
771 Create a new tilemap of <w>*<h> tiles, each of <bw>*<bh> pixels and return
775 \begin_layout Subsubsection
776 TILEMAP:getsize: Query tilemap size
779 \begin_layout Itemize
780 Syntax: width, height tmap:getsize()
783 \begin_layout Standard
787 \begin_layout Itemize
788 tmap: TILEMAP: The tilemap to query.
791 \begin_layout Standard
795 \begin_layout Itemize
796 width: number : The width of the tilemap in tiles.
799 \begin_layout Itemize
800 height: number: The height of the tilemap in tiles.
803 \begin_layout Standard
804 Get size of tilemap in tiles.
807 \begin_layout Subsubsection
808 TILEMAP:getcsize: Query tilemap cell size
811 \begin_layout Itemize
812 Syntax: width, height tmap:getcsize()
815 \begin_layout Standard
819 \begin_layout Itemize
820 tmap: TILEMAP: The tilemap to query.
823 \begin_layout Standard
827 \begin_layout Itemize
828 width: number: The width of tilemap tile in pixels.
831 \begin_layout Itemize
832 height: number: The height of tilemap tile in pixels.
835 \begin_layout Standard
836 Get size of each tilemap tile in pixels.
839 \begin_layout Subsubsection
840 TILEMAP:get: Query tilemap tile
843 \begin_layout Itemize
844 Syntax: bitmap, palette tmap:get(x, y)
847 \begin_layout Standard
851 \begin_layout Itemize
852 tmap: TILEMAP: The tilemap to query.
855 \begin_layout Itemize
856 x: number: The x-coordinate of tile to query.
859 \begin_layout Itemize
860 y: number: The y-coordinate of tile to query.
863 \begin_layout Standard
867 \begin_layout Itemize
868 bitmap: The associated bitmap (BITMAP or DBITMAP), or nil if none.
871 \begin_layout Itemize
872 palette: The palette (PALETTE) associated with indexed-color bitmap, if
877 \begin_layout Standard
878 Return the contents of tile at <x>,<y>.
881 \begin_layout Subsubsection
882 TILEMAP:set: Set tilemap cell
885 \begin_layout Itemize
886 Syntax: tmap:set(x, y)
889 \begin_layout Itemize
890 Syntax: tmap:set(x, y, bitmap)
893 \begin_layout Itemize
894 Syntax: tmap:set(x, y, bitmap, palette)
897 \begin_layout Standard
901 \begin_layout Itemize
902 tmap: TILEMAP: The tilemap to manipulate.
905 \begin_layout Itemize
906 number x: The x-coordinate of tile to set.
909 \begin_layout Itemize
910 number y: The y-coordinate of tile to set.
913 \begin_layout Itemize
914 bitmap: BITMAP/DBITMAP: The bitmap to set to tile.
917 \begin_layout Itemize
918 palette: PALETTE: The associated palette for bitmap.
921 \begin_layout Standard
922 Set the contents of tile <x>,<y>.
923 If no <bitmap> is given, clears the tile.
924 Otherwise sets the tile to contain bitmap <bitmap> with associated palette
928 \begin_layout Itemize
929 Specifying index bitmap <bitmap> without palette <palette> causes an error.
932 \begin_layout Subsubsection
933 TILEMAP:scroll: Scroll tilemap
936 \begin_layout Itemize
937 Syntax: tmap:scroll(ox, oy);
940 \begin_layout Itemize
941 Syntax: tmap:scroll(ox, oy, x, y, w, h);
944 \begin_layout Itemize
945 Syntax: tmap:scroll(ox, oy, x, y, w, h, circ_x, circ_y);
948 \begin_layout Standard
952 \begin_layout Itemize
953 tmap: TILEMAP: The tilemap to manipulate.
956 \begin_layout Itemize
957 ox: number: The number of tiles to scroll horizontally (positive is to right).
960 \begin_layout Itemize
961 oy: number: The number of tiles to scroll vertically (positive is to down).
964 \begin_layout Itemize
965 x: number: The left edge of scroll window.
968 \begin_layout Itemize
969 y: number: The top edge of scroll window.
972 \begin_layout Itemize
973 w: number: The width of scroll window.
976 \begin_layout Itemize
977 h: number: The height of scroll window.
980 \begin_layout Itemize
981 circ_x: boolean: If true, treat the window as circular in horizontal direction.
984 \begin_layout Itemize
985 circ_y: boolean: If true, treat the window as circular in vertical direction.
988 \begin_layout Standard
989 Scroll the specified tilemap <tmap> by <ox>,<oy>.
990 If a window <x>,<y>,<w>,<h> is specified, only that part is scrolled.
991 <circ_x> and <circ_y> control if scroll is circular or not.
994 \begin_layout Itemize
995 Specifying out-of-range window causes an error.
998 \begin_layout Subsubsection
999 TILEMAP:draw: Draw tilemap
1002 \begin_layout Itemize
1003 Name: tmap:draw(x, y)
1006 \begin_layout Itemize
1007 Name: tmap:draw(x, y, x0, y0, w, h)
1010 \begin_layout Standard
1014 \begin_layout Itemize
1015 tmap: TILEMAP: The tilemap to draw.
1018 \begin_layout Itemize
1019 x: The x coordinate on screen to draw to.
1022 \begin_layout Itemize
1023 y: The y coordinate on screen to draw to.
1026 \begin_layout Itemize
1027 x0: number: The x coordinate on tilemap (in pixels) to start drawing from.
1030 \begin_layout Itemize
1031 y0: number: The y coordinate on tilemap (in pixels) to start drawing from.
1034 \begin_layout Itemize
1035 w: number: The width to draw (in pixels).
1038 \begin_layout Itemize
1039 h: number: The height to draw (in pixels).
1042 \begin_layout Standard
1043 Draw tilemap <tmap> to screen at <x>,<y>.
1044 If a window <x0>,<y0>,<w>,<h> is specified, only that part is drawn.
1047 \begin_layout Itemize
1048 This method requires a rendering context to work.
1051 \begin_layout Subsubsection
1052 TILEMAP:draw_outside: Draw tilemap outside game area
1055 \begin_layout Itemize
1056 Name: tmap:draw_outside(x, y)
1059 \begin_layout Itemize
1060 Name: tmap:draw_outside(x, y, x0, y0, w, h)
1063 \begin_layout Standard
1064 Like TILEMAP:draw, but draws only outside game area.
1067 \begin_layout Standard
1068 \begin_inset Newpage pagebreak
1074 \begin_layout Subsection
1075 RENDERCTX: Off-screen rendering context
1078 \begin_layout Standard
1079 Object acting as off-screen rendering context.
1082 \begin_layout Subsubsection
1083 Static function new: Create a render queue
1086 \begin_layout Itemize
1087 Syntax: renderctx gui.renderctx.new(width, height);
1090 \begin_layout Itemize
1091 Syntax: renderctx classes.RENDERCTX.new(width, height);
1094 \begin_layout Itemize
1095 Deprecated: renderctx gui.renderq_new(width, height);
1098 \begin_layout Standard
1102 \begin_layout Itemize
1103 width: number: The notional width of the game area.
1106 \begin_layout Itemize
1107 height: number: The notional height of the game area.
1110 \begin_layout Standard
1114 \begin_layout Itemize
1115 rendectx: RENDERCTX: The newly created render context.
1118 \begin_layout Standard
1119 Create a render context with reported size <width>*<height> and return it.
1122 \begin_layout Subsubsection
1123 Static function setnull: Reset to default queue
1126 \begin_layout Itemize
1127 Syntax: gui.renderctx.setnull()
1130 \begin_layout Itemize
1131 Syntax: classes.RENDERCTX:setnull()
1134 \begin_layout Itemize
1135 Deprecated: gui.renderq_set()
1138 \begin_layout Standard
1139 Reset the used render context back to default for the executing callback:
1142 \begin_layout Itemize
1143 The default for paint callback is the screen
1146 \begin_layout Itemize
1147 The default for video callback is the video frame
1150 \begin_layout Itemize
1151 The default otherwise is nothing.
1154 \begin_layout Subsubsection
1155 Method clear: Clear a render queue
1158 \begin_layout Itemize
1159 Syntax: renderctx:clear()
1162 \begin_layout Itemize
1163 Deprecated: gui.renderq_clear(renderctx)
1166 \begin_layout Standard
1170 \begin_layout Itemize
1171 renderctx: RENDERCTX: The render queue to clear.
1174 \begin_layout Standard
1175 Clear all drawing from the context.
1178 \begin_layout Subsubsection
1179 Method set: Change active render context
1182 \begin_layout Itemize
1183 Syntax: renderctx:set()
1186 \begin_layout Itemize
1187 Deprecated: gui.renderq_set(renderctx)
1190 \begin_layout Standard
1194 \begin_layout Itemize
1195 renderctx: RENDERCTX: The render queue to use.
1198 \begin_layout Standard
1199 Switch the current rendering context <renderctx>.
1202 \begin_layout Subsubsection
1203 Method run: Draw all objects in context to another
1206 \begin_layout Itemize
1207 Syntax: renderctx:run()
1210 \begin_layout Itemize
1211 Deprecated: gui.renderq_run(renderctx)
1214 \begin_layout Standard
1218 \begin_layout Itemize
1219 renderctx: RENDERCTX: The render context to overlay.
1222 \begin_layout Standard
1223 Overlay the specified render context <context> upon the active rendering
1227 \begin_layout Itemize
1228 Trying to overlay rendering context upon itself is a bad idea.
1231 \begin_layout Subsubsection
1232 Method render: Render a contex to bitmap
1235 \begin_layout Itemize
1236 Syntax: bitmap renderctx:render()
1239 \begin_layout Standard
1243 \begin_layout Itemize
1244 renderctx: RENDERCTX: The context to render.
1247 \begin_layout Standard
1251 \begin_layout Itemize
1252 bitmap: DBITMAP: The rendered bitmap.
1255 \begin_layout Standard
1256 Render the specified context <renderctx> to a new bitmap.
1259 \begin_layout Itemize
1260 The size of bitmap will be nominal game area size, plus any set gaps.
1263 \begin_layout Itemize
1264 This method does not require active rendering context.
1267 \begin_layout Subsubsection
1268 Method synchronous_repaint: Paint screen now
1271 \begin_layout Itemize
1272 Syntax: renderctx:synchronous_repaint()
1275 \begin_layout Itemize
1276 Deprecated: gui.synchronous_repaint(renderctx)
1279 \begin_layout Standard
1283 \begin_layout Itemize
1284 renderctx: RENDERCTX: The context to paint.
1287 \begin_layout Standard
1288 Immediately redraw the screen with game overlayed by drawings from context
1292 \begin_layout Itemize
1293 This does not require active rendering context.
1296 \begin_layout Itemize
1297 Will not cause paint callback to be invoked.
1300 \begin_layout Standard
1301 \begin_inset Newpage pagebreak
1307 \begin_layout Subsection
1308 PALETTE: Color palette for indexed image
1311 \begin_layout Subsubsection
1312 Static function new: Create a new palette
1315 \begin_layout Itemize
1316 Syntax: palette gui.palette.new()
1319 \begin_layout Itemize
1320 Syntax: palette classes.PALETTE.new()
1323 \begin_layout Itemize
1324 Deprecated: palette gui.palette_new()
1327 \begin_layout Standard
1331 \begin_layout Itemize
1332 palette: PALETTE: The created palette.
1335 \begin_layout Standard
1336 Create a new palette (with all colors transparent) and return it.
1339 \begin_layout Subsubsection
1340 Static function load: Load a palette
1343 \begin_layout Itemize
1344 Syntax: palette gui.palette.load(file, [base])
1347 \begin_layout Itemize
1348 Syntax: palette classes.PALETTE.load(file, [base])
1351 \begin_layout Itemize
1352 Deprecated: palette gui.palette_load(file, [base])
1355 \begin_layout Standard
1359 \begin_layout Itemize
1360 string file: The file to load.
1363 \begin_layout Itemize
1364 string base (optional): The base file to resolve file relative to.
1367 \begin_layout Standard
1371 \begin_layout Itemize
1372 palette: PALETTE: The loaded palette.
1375 \begin_layout Standard
1376 Load a palette from file <file> (resolved relative to <base>).
1379 \begin_layout Itemize
1380 The file format is a series of lines, each with following format:
1384 \begin_layout Itemize
1385 Blank or just whitespace: Ignored
1388 \begin_layout Itemize
1389 First non-whitespace is '#': Ignored
1392 \begin_layout Itemize
1393 <r> <g> <b>: Fully opaque color with specified RGB values (0-255)
1396 \begin_layout Itemize
1397 <r> <g> <b> <a>: Color with specified RGB values (0-255) and specified alpha
1398 (0-256, 0 being fully transparent and 256 fully opaque).
1401 \begin_layout Itemize
1402 transparent: Fully transparent color
1406 \begin_layout Subsubsection
1407 Static function load_str: Load a palette from string
1410 \begin_layout Itemize
1411 Syntax: palette gui.palette.load(data)
1414 \begin_layout Itemize
1415 Syntax: palette classes.PALETTE.load(data)
1418 \begin_layout Itemize
1419 Deprecated: palette gui.palette_load(data)
1422 \begin_layout Standard
1426 \begin_layout Itemize
1427 string data: The palette data.
1430 \begin_layout Standard
1434 \begin_layout Itemize
1435 palette: PALETTE: The loaded palette.
1438 \begin_layout Standard
1439 Like PALETTE:load, but instead of reading palette from file, reads it from
1443 \begin_layout Subsubsection
1444 Method set: Set palette entry
1447 \begin_layout Itemize
1448 Syntax: palette:set(index, color)
1451 \begin_layout Itemize
1452 Deprecated: gui.palette_set(palette, ...)
1455 \begin_layout Standard
1459 \begin_layout Itemize
1460 palette: PALETTE: The palette to manipulate
1463 \begin_layout Itemize
1464 index: number: The index of color to set (0-65535).
1467 \begin_layout Itemize
1468 color: number/string: The color value to set.
1471 \begin_layout Standard
1472 Set palette <palette> index <index> to color <color>.
1475 \begin_layout Subsubsection
1476 Method hash: Hash a palette
1479 \begin_layout Itemize
1480 Syntax: hash palette:hash()
1483 \begin_layout Itemize
1484 Deprecated: hash gui.palette_hash(palette)
1487 \begin_layout Standard
1491 \begin_layout Itemize
1492 palette: The palette to hash.
1495 \begin_layout Standard
1499 \begin_layout Itemize
1500 hash: string: 64-hex digit hash.
1503 \begin_layout Standard
1504 Obtain crypto-grade hash of palette data of <palette>.
1507 \begin_layout Itemize
1508 All colors after the last non-transparent one are ignored.
1511 \begin_layout Subsubsection
1512 Method adjust_transparency: Adjust transparency
1515 \begin_layout Itemize
1516 Syntax: palette:adjust_transparency(newvalue)
1519 \begin_layout Itemize
1520 Deprecated: gui.adjust_transparency(palette, ...)
1523 \begin_layout Standard
1527 \begin_layout Itemize
1528 palette: PALETTE: The palette to adjust.
1531 \begin_layout Itemize
1532 Number adj: The factor to multiply opaqueness with times 256.
1535 \begin_layout Standard
1536 Multiply opaqueness of all colors in palette <palette> by factor of <adj>/256.
1539 \begin_layout Standard
1540 \begin_inset Newpage pagebreak
1546 \begin_layout Subsection
1547 BITMAP: Indexed-color bitmap
1550 \begin_layout Subsubsection
1551 Static function new: Create a new bitmap
1554 \begin_layout Itemize
1555 Syntax: bitmap gui.bitmap.new(w, h, [fillcolor])
1558 \begin_layout Itemize
1559 Syntax: bitmap classes.BITMAP.new(w, h, [fillcolor])
1562 \begin_layout Itemize
1563 Deprecated: bitmap gui.bitmap_new(w, h, false, [fillcolor])
1566 \begin_layout Standard
1570 \begin_layout Itemize
1571 w: number: The width of bitmap to create in pixels.
1574 \begin_layout Itemize
1575 h: number: The height of bitmap to create in pixels.
1578 \begin_layout Itemize
1579 false: boolean: Constant boolean false.
1582 \begin_layout Itemize
1583 fillcolor: number: The initial fill index.
1584 Default 0 if not specified.
1587 \begin_layout Standard
1588 Create a new bitmap of size <w>*<h>.
1589 Fill the bitmap with color index <fillcolor>.
1592 \begin_layout Subsubsection
1593 Method draw: Draw a bitmap
1596 \begin_layout Itemize
1597 Syntax: bitmap:draw(x, y, palette)
1600 \begin_layout Itemize
1601 Deprecated: gui.bitmap_draw(x, y, bitmap, palette)
1604 \begin_layout Standard
1608 \begin_layout Itemize
1609 bitmap: BITMAP: The bitmap to draw
1612 \begin_layout Itemize
1613 x: number: The x-coordinate on screen.
1616 \begin_layout Itemize
1617 y: number: The y-coordinate on screen.
1620 \begin_layout Itemize
1621 palette: The palette to use for drawing.
1624 \begin_layout Standard
1625 Draw bitmap <bitmap> on screen at <x>,<y> with palette <palette>.
1628 \begin_layout Subsubsection
1629 Method draw_outside: Draw a bitmap outside game area
1632 \begin_layout Itemize
1633 Syntax: bitmap:draw_outside(x, y, palette)
1636 \begin_layout Standard
1637 Like bitmap:draw, but does not draw on game area.
1640 \begin_layout Subsubsection
1641 Method draw_clip: Draw a bitmap, with clipping
1644 \begin_layout Itemize
1645 Syntax: bitmap:draw_clip(x, y, palette, x0, y0, width, height)
1648 \begin_layout Standard
1652 \begin_layout Itemize
1653 bitmap: BITMAP: The bitmap to draw
1656 \begin_layout Itemize
1657 x: number: The x-coordinate on screen.
1660 \begin_layout Itemize
1661 y: number: The y-coordinate on screen.
1664 \begin_layout Itemize
1665 palette: The palette to use for drawing.
1668 \begin_layout Itemize
1669 x0: The smallest bitmap x coordinate to draw.
1672 \begin_layout Itemize
1673 y0: The smallest bitmap y coordinate to draw.
1676 \begin_layout Itemize
1677 width: Width of region to draw
1680 \begin_layout Itemize
1681 height: Height of region to draw.
1684 \begin_layout Standard
1685 Like bitmap:draw, but clip the bitmap area drawn.
1688 \begin_layout Subsubsection
1689 Method draw_clip_outside: Draw a bitmap outside game are, with clipping
1692 \begin_layout Itemize
1693 Syntax: bitmap:draw_clip_outside(x, y, palette, x0, y0, width, height)
1696 \begin_layout Standard
1697 Like bitmap:draw_clip, but only draw outside game area.
1700 \begin_layout Subsubsection
1701 Method pset: Set pixel in bitmap
1704 \begin_layout Itemize
1705 Syntax: bitmap:pset(x, y, color)
1708 \begin_layout Itemize
1709 Deprecaed: gui.bitmap_pset(bitmap, ...)
1712 \begin_layout Standard
1716 \begin_layout Itemize
1717 bitmap: BITMAP: The bitmap to manipulate.
1720 \begin_layout Itemize
1721 x: number: x-coordinate of pixel to set.
1724 \begin_layout Itemize
1725 y: number: y-coordinate of pixel to set.
1728 \begin_layout Itemize
1729 color: number: The color index to set.
1732 \begin_layout Standard
1733 Sets specified pixel <x>,<y> in bitmap <bitmap> to color index <color>.
1736 \begin_layout Subsubsection
1737 Method pget: Get pixel in bitmap
1740 \begin_layout Itemize
1741 Syntax: color bitmap:pget(x,y)
1744 \begin_layout Itemize
1745 Deprecated: color gui.bitmap_pget(bitmap, ...)
1748 \begin_layout Standard
1752 \begin_layout Itemize
1753 bitmap: BITMAP: The bitmap to query.
1756 \begin_layout Itemize
1757 x: number: x-coordinate of pixel to get.
1760 \begin_layout Itemize
1761 y: number: y-coordinate of pixel to get.
1764 \begin_layout Standard
1768 \begin_layout Itemize
1769 color: number: The color index in specified pixel.
1772 \begin_layout Standard
1773 Gets color index of specified pixel <x>,<y> in bitmap <bitmap>.
1776 \begin_layout Subsubsection
1777 Method size: Get size of bitmap
1780 \begin_layout Itemize
1781 Syntax: width, height bitmap:size()
1784 \begin_layout Itemize
1785 Syntax: width, height gui.bitmap_size(bitmap)
1788 \begin_layout Standard
1792 \begin_layout Itemize
1793 bitmap: BITMAP: The bitmap to query.
1796 \begin_layout Standard
1800 \begin_layout Itemize
1801 width: number: The width of the bitmap.
1804 \begin_layout Itemize
1805 height: number: The height of the bitmap.
1808 \begin_layout Standard
1809 Get size of bitmap <bitmap>.
1812 \begin_layout Subsubsection
1813 Method blit: Blit a bitmap into another
1816 \begin_layout Itemize
1817 Syntax: dest:blit(dx, dy, src, sx, sy, w, h, [ck])
1820 \begin_layout Itemize
1821 Deprecated: gui.bitmap_blit(dest, ...)
1824 \begin_layout Standard
1828 \begin_layout Itemize
1829 dest: BITMAP: The target bitmap to blit to.
1832 \begin_layout Itemize
1833 dx: number: The x-coordinate in target.
1836 \begin_layout Itemize
1837 dy: number: The y-coordinate in target.
1840 \begin_layout Itemize
1841 src: BITMAP: The source bitmap.
1844 \begin_layout Itemize
1845 sx: number: The x-coordinate in source.
1848 \begin_layout Itemize
1849 sy: number: The y-coordinate in source.
1852 \begin_layout Itemize
1853 w: number: The width of area to blit.
1856 \begin_layout Itemize
1857 h: number: The height of area to blit.
1860 \begin_layout Itemize
1861 ck: number: The color key.
1862 Pixels with this index are not copied.
1866 \begin_layout Itemize
1867 If none is specified, all pixels are copied.
1871 \begin_layout Standard
1872 Copy region of size <w>*<h> at <sx>,<sy> in bitmap <src> into <dest> at
1874 If a color key <ck> is specified, pixels of that color are not copied.
1877 \begin_layout Subsubsection
1878 Method blit_scaled: Blit a bitmap into another with scaling
1881 \begin_layout Itemize
1882 Syntax: dest:blit_scaled(dx, dy, src, sx, sy, w, h, hscl, [vscl], [ck])
1885 \begin_layout Itemize
1886 Deprecated: gui.bitmap_blit_scaled(dest, ...)
1889 \begin_layout Standard
1893 \begin_layout Itemize
1894 dest: BITMAP: The target bitmap to blit to.
1897 \begin_layout Itemize
1898 dx: number: The x-coordinate in target.
1901 \begin_layout Itemize
1902 dy: number: The y-coordinate in target.
1905 \begin_layout Itemize
1906 src: BITMAP: The source bitmap.
1909 \begin_layout Itemize
1910 sx: number: The x-coordinate in source.
1913 \begin_layout Itemize
1914 sy: number: The y-coordinate in source.
1917 \begin_layout Itemize
1918 w: number: The width of area to blit.
1921 \begin_layout Itemize
1922 h: number: The height of area to blit.
1925 \begin_layout Itemize
1926 hscl: number: Horizontal scale factor (integer).
1929 \begin_layout Itemize
1930 vscl: number: Vertical scale factor (integer).
1931 Defaults to the same as <hscl>.
1934 \begin_layout Itemize
1935 ck: number: The color key.
1936 Pixels with this index are not copied.
1940 \begin_layout Itemize
1941 If none is specified, all pixels are copied.
1945 \begin_layout Standard
1946 Like BITMAP:blit, but also scales the copied part of bitmap (using nearest
1947 neighbor) by factor of <hscl>*<vscl>.
1950 \begin_layout Subsubsection
1951 Method blit_porterduff: Blit a bitmap into another with Porter-Duff composition
1954 \begin_layout Itemize
1955 Syntax: dest:blit_porterduff(dx, dy, src, sx, sy, w, h, operator)
1958 \begin_layout Itemize
1959 Deprecated: gui.bitmap_blit_porterduff(dest, ...)
1962 \begin_layout Standard
1966 \begin_layout Itemize
1967 dest: BITMAP: The target bitmap to blit to.
1970 \begin_layout Itemize
1971 dx: number: The x-coordinate in target.
1974 \begin_layout Itemize
1975 dy: number: The y-coordinate in target.
1978 \begin_layout Itemize
1979 src: BITMAP: The source bitmap.
1982 \begin_layout Itemize
1983 sx: number: The x-coordinate in source.
1986 \begin_layout Itemize
1987 sy: number: The y-coordinate in source.
1990 \begin_layout Itemize
1991 w: number: The width of area to blit.
1994 \begin_layout Itemize
1995 h: number: The height of area to blit.
1998 \begin_layout Itemize
1999 operator: string: The operator to use.
2003 \begin_layout Itemize
2004 Can be one of: Src, Atop, Over, In, Out, Dest, DestAtop, DestOver, DestIn,
2005 DestOut, Clear or Xor.
2009 \begin_layout Standard
2010 Like BITMAP:blit, but instead of just overwriting, applies specified Porter-Duff
2015 \begin_layout Itemize
2016 Color index 0 in source and target is treated as background.
2019 \begin_layout Subsubsection
2020 Method blit_scaled_porterduff: Blit a bitmap into another with scaling and
2021 Porter-Duff composition
2024 \begin_layout Itemize
2025 Syntax: dest:blit_scaled_porterduff(dx, dy, src, sx, sy, w, h, hscl, [vscl],
2029 \begin_layout Itemize
2030 Deprecated: gui.bitmap_blit_scaled_porterduff(dest, ...)
2033 \begin_layout Standard
2037 \begin_layout Itemize
2038 dest: BITMAP: The target bitmap to blit to.
2041 \begin_layout Itemize
2042 dx: number: The x-coordinate in target.
2045 \begin_layout Itemize
2046 dy: number: The y-coordinate in target.
2049 \begin_layout Itemize
2050 src: BITMAP: The source bitmap.
2053 \begin_layout Itemize
2054 sx: number: The x-coordinate in source.
2057 \begin_layout Itemize
2058 sy: number: The y-coordinate in source.
2061 \begin_layout Itemize
2062 w: number: The width of area to blit.
2065 \begin_layout Itemize
2066 h: number: The height of area to blit.
2069 \begin_layout Itemize
2070 hscl: number: Horizontal scale factor (integer).
2073 \begin_layout Itemize
2074 vscl: number: Vertical scale factor (integer).
2075 Defaults to the same as <hscl>.
2078 \begin_layout Itemize
2079 operator: string: The operator to use.
2083 \begin_layout Itemize
2084 Can be one of: Src, Atop, Over, In, Out, Dest, DestAtop, DestOver, DestIn,
2085 DestOut, Clear or Xor.
2089 \begin_layout Standard
2090 Like BITMAP:blit_porterduff, but also scales the source by <hscl>*<vscl>
2091 like BITMAP:blit_scaled.
2094 \begin_layout Subsubsection
2095 Method blit_priority: Blit a bitmap into another with color priority
2098 \begin_layout Itemize
2099 Syntax: dest:blit_priority(dx, dy, src, sx, sy, w, h)
2102 \begin_layout Itemize
2103 Deprecated: gui.bitmap_blit_priority(dest, ...)
2106 \begin_layout Standard
2110 \begin_layout Itemize
2111 dest: BITMAP: The target bitmap to blit to.
2114 \begin_layout Itemize
2115 dx: number: The x-coordinate in target.
2118 \begin_layout Itemize
2119 dy: number: The y-coordinate in target.
2122 \begin_layout Itemize
2123 src: BITMAP: The source bitmap.
2126 \begin_layout Itemize
2127 sx: number: The x-coordinate in source.
2130 \begin_layout Itemize
2131 sy: number: The y-coordinate in source.
2134 \begin_layout Itemize
2135 w: number: The width of area to blit.
2138 \begin_layout Itemize
2139 h: number: The height of area to blit.
2142 \begin_layout Standard
2143 Like BITMAP:blit, but only copy pixels where source color index is greater
2144 than destination color index.
2147 \begin_layout Subsubsection
2148 Method blit_scaled_priority: Blit a bitmap into another with color priority
2152 \begin_layout Itemize
2153 Syntax: dest:blit_scaled_priority(dx, dy, src, sx, sy, w, h, hscl, [vscl])
2156 \begin_layout Itemize
2157 Deprecated: gui.bitmap_blit_scaled_priority(dest, ...)
2160 \begin_layout Standard
2164 \begin_layout Itemize
2165 dest: BITMAP: The target bitmap to blit to.
2168 \begin_layout Itemize
2169 dx: number: The x-coordinate in target.
2172 \begin_layout Itemize
2173 dy: number: The y-coordinate in target.
2176 \begin_layout Itemize
2177 src: BITMAP: The source bitmap.
2180 \begin_layout Itemize
2181 sx: number: The x-coordinate in source.
2184 \begin_layout Itemize
2185 sy: number: The y-coordinate in source.
2188 \begin_layout Itemize
2189 w: number: The width of area to blit.
2192 \begin_layout Itemize
2193 h: number: The height of area to blit.
2196 \begin_layout Itemize
2197 hscl: number: Horizontal scale factor (integer).
2200 \begin_layout Itemize
2201 vscl: number: Vertical scale factor (integer).
2202 Defaults to the same as <hscl>.
2205 \begin_layout Standard
2206 Like BITMAP:blit_priority, but apply scaling by <hscl>*<vscl> like BITMAP:blit_s
2210 \begin_layout Subsubsection
2211 Method save_png: Save a bitmap to PNG
2214 \begin_layout Itemize
2215 Syntax: bitmap:save_png(filename, [base], palette)
2218 \begin_layout Itemize
2219 Syntax: data bitmap:save_png(palette)
2222 \begin_layout Itemize
2224 gui.bitmap_save_png(bitmap, ...)
2227 \begin_layout Standard
2231 \begin_layout Itemize
2232 bitmap: BITMAP: The bitmap to save.
2235 \begin_layout Itemize
2236 filename: string: The filename to save to.
2239 \begin_layout Itemize
2240 base: string: The base filename is resolved relative to.
2243 \begin_layout Itemize
2244 palette: PALETTE: The palette to use.
2247 \begin_layout Standard
2251 \begin_layout Itemize
2252 data: string: BASE64 encoded PNG data.
2255 \begin_layout Standard
2256 Save bitmap <bitmap>, with palette <pal> into PNG file <filename> (relative
2257 to <base>) or return BASE64 encoding of it.
2260 \begin_layout Subsubsection
2261 Method hash: Hash a bitmap
2264 \begin_layout Itemize
2265 Syntax: hash bitmap:hash()
2268 \begin_layout Itemize
2269 Deprecated: hash bitmap:hash(bitmap)
2272 \begin_layout Standard
2276 \begin_layout Itemize
2277 bitmap: BITMAP: The bitmap to hash.
2280 \begin_layout Standard
2284 \begin_layout Itemize
2285 hash: string: 64-hex digit hash
2288 \begin_layout Standard
2289 Hashes bitmap <bitmap> and returns crypto-strong hash.
2293 \begin_layout Itemize
2294 Color order in bitmap is significant.
2297 \begin_layout Standard
2298 \begin_inset Newpage pagebreak
2304 \begin_layout Subsection
2305 DBITMAP: Direct-color bitmap
2308 \begin_layout Subsubsection
2309 Static function: new: Create a new bitmap
2312 \begin_layout Itemize
2313 Syntax: bitmap gui.dbitmap.new(w, h, [fillcolor])
2316 \begin_layout Itemize
2317 Syntax: bitmap classes.DBITMAP.new(w, h, [fillcolor])
2320 \begin_layout Itemize
2321 Deprecated: bitmap gui.bitmap_new (w, h, true, [fillcolor]).
2324 \begin_layout Standard
2328 \begin_layout Itemize
2329 w: number: The width of new bitmap.
2332 \begin_layout Itemize
2333 h: number: The height of new bitmap.
2336 \begin_layout Itemize
2337 true: boolean: Fixed boolean true
2340 \begin_layout Itemize
2341 fillcolor: The color to fill the bitmap with (default transparent).
2344 \begin_layout Standard
2348 \begin_layout Itemize
2349 bitmap: DBITMAP: The new bitmap.
2352 \begin_layout Standard
2353 Create a new direct-color bitmap of size <w>*<h>, initially filled with
2357 \begin_layout Subsubsection
2358 Method draw: Draw a bitmap
2361 \begin_layout Itemize
2362 Syntax: bitmap.draw(x, y)
2365 \begin_layout Itemize
2366 Deprecated: gui.bitmap_draw(x, y, bitmap)
2369 \begin_layout Standard
2373 \begin_layout Itemize
2374 bitmap: DBITMAP: The bitmap to draw.
2377 \begin_layout Itemize
2378 x: number: X-coordinate on screen.
2381 \begin_layout Itemize
2382 y: number: Y-coordinate on screen.
2385 \begin_layout Standard
2386 Draw bitmap <bitmap> on screen at <x>,<y>.
2389 \begin_layout Subsubsection
2390 Method draw_outside: Draw a bitmap outside game area
2393 \begin_layout Itemize
2394 Syntax: dbitmap:draw_outside(x, y, palette)
2397 \begin_layout Standard
2398 Like dbitmap:draw, but does not draw on game area.
2401 \begin_layout Subsubsection
2402 Method draw_clip: Draw a bitmap, with clipping
2405 \begin_layout Itemize
2406 Syntax: dbitmap:draw(x, y, palette, x0, y0, width, height)
2409 \begin_layout Standard
2413 \begin_layout Itemize
2414 bitmap: DBITMAP: The bitmap to draw
2417 \begin_layout Itemize
2418 x: number: The x-coordinate on screen.
2421 \begin_layout Itemize
2422 y: number: The y-coordinate on screen.
2425 \begin_layout Itemize
2426 x0: The smallest bitmap x coordinate to draw.
2429 \begin_layout Itemize
2430 y0: The smallest bitmap y coordinate to draw.
2433 \begin_layout Itemize
2434 width: Width of region to draw
2437 \begin_layout Itemize
2438 height: Height of region to draw.
2441 \begin_layout Standard
2442 Like dbitmap:draw, but clip the bitmap area drawn.
2445 \begin_layout Subsubsection
2446 Method draw_clip_outside: Draw a bitmap outside game are, with clipping
2449 \begin_layout Itemize
2450 Syntax: dbitmap:draw_clip_outside(x, y, palette, x0, y0, width, height)
2453 \begin_layout Standard
2454 Like dbitmap:draw_clip, but only draw outside game area.
2457 \begin_layout Subsubsection
2458 Method pset: Set pixel in bitmap
2461 \begin_layout Itemize
2462 Syntax: bitmap:pset(x, y, color)
2465 \begin_layout Itemize
2466 Deprecaed: gui.bitmap_pset(bitmap, ...)
2469 \begin_layout Standard
2473 \begin_layout Itemize
2474 bitmap: DBITMAP: The bitmap to manipulate.
2477 \begin_layout Itemize
2478 x: number: x-coordinate of pixel to set.
2481 \begin_layout Itemize
2482 y: number: y-coordinate of pixel to set.
2485 \begin_layout Itemize
2486 color: number/string: The color to set.
2489 \begin_layout Standard
2490 Sets specified pixel <x>,<y> in bitmap <bitmap> to color <color>.
2493 \begin_layout Subsubsection
2494 Method pget: Get pixel in bitmap
2497 \begin_layout Itemize
2498 Syntax: color bitmap:pget(x,y)
2501 \begin_layout Itemize
2502 Deprecated: color gui.bitmap_pget(bitmap, ...)
2505 \begin_layout Standard
2509 \begin_layout Itemize
2510 bitmap: DBITMAP: The bitmap to query.
2513 \begin_layout Itemize
2514 x: number: x-coordinate of pixel to get.
2517 \begin_layout Itemize
2518 y: number: y-coordinate of pixel to get.
2521 \begin_layout Standard
2525 \begin_layout Itemize
2526 color: number: The color of specified pixel.
2529 \begin_layout Standard
2530 Gets color index of specified pixel <x>,<y> in bitmap <bitmap>.
2533 \begin_layout Subsubsection
2534 Method size: Get size of bitmap
2537 \begin_layout Itemize
2538 Syntax: width, height bitmap:size()
2541 \begin_layout Itemize
2542 Syntax: width, height gui.bitmap_size(bitmap)
2545 \begin_layout Standard
2549 \begin_layout Itemize
2550 bitmap: DBITMAP: The bitmap to query.
2553 \begin_layout Standard
2557 \begin_layout Itemize
2558 width: number: The width of the bitmap.
2561 \begin_layout Itemize
2562 height: number: The height of the bitmap.
2565 \begin_layout Standard
2566 Get size of bitmap <bitmap>.
2569 \begin_layout Subsubsection
2570 Method blit: Blit a bitmap into another
2573 \begin_layout Itemize
2574 Syntax: dest:blit(dx, dy, src, sx, sy, w, h, [ck])
2577 \begin_layout Itemize
2578 Syntax: dest:blit(dx, dy, src, srcpal, sx, sy, w, h, [ck])
2581 \begin_layout Itemize
2582 Deprecated: gui.bitmap_blit(dest, ...)
2585 \begin_layout Standard
2589 \begin_layout Itemize
2590 dest: DBITMAP: The target bitmap to blit to.
2593 \begin_layout Itemize
2594 dx: number: The x-coordinate in target.
2597 \begin_layout Itemize
2598 dy: number: The y-coordinate in target.
2601 \begin_layout Itemize
2602 src: BITMAP/DBITMAP: The source bitmap.
2605 \begin_layout Itemize
2606 srcpal: PALETTE: If <src> is indexed, this is the palette for source.
2609 \begin_layout Itemize
2610 sx: number: The x-coordinate in source.
2613 \begin_layout Itemize
2614 sy: number: The y-coordinate in source.
2617 \begin_layout Itemize
2618 w: number: The width of area to blit.
2621 \begin_layout Itemize
2622 h: number: The height of area to blit.
2625 \begin_layout Itemize
2626 ck: number: The color key.
2627 Pixels with this index are not copied.
2631 \begin_layout Itemize
2632 If none is specified, all pixels are copied.
2635 \begin_layout Itemize
2636 If <src> is paletted, this is color index, otherwise it is a color.
2640 \begin_layout Standard
2641 Copy region of size <w>*<h> at <sx>,<sy> in bitmap <src> (with palette <pal>
2642 if indexed) into <dest> at <dx>,<dy>.
2643 If a color key <ck> is specified, pixels of that color are not copied.
2646 \begin_layout Subsubsection
2647 Method blit_scaled: Blit a bitmap into another with scaling
2650 \begin_layout Itemize
2651 Syntax: dest:blit_scaled(dx, dy, src, sx, sy, w, h, hscl, [vscl], [ck])
2654 \begin_layout Itemize
2655 Syntax: dest:blit_scaled(dx, dy, src, srcpal, sx, sy, w, h, hscl, [vscl],
2659 \begin_layout Itemize
2660 Deprecated: gui.bitmap_blit_scaled(dest, ...)
2663 \begin_layout Standard
2667 \begin_layout Itemize
2668 dest: DBITMAP: The target bitmap to blit to.
2671 \begin_layout Itemize
2672 dx: number: The x-coordinate in target.
2675 \begin_layout Itemize
2676 dy: number: The y-coordinate in target.
2679 \begin_layout Itemize
2680 src: BITMAP/DBITMAP: The source bitmap.
2683 \begin_layout Itemize
2684 srcpal: PALETTE: If <src> is indexed, this is the palette for source.
2687 \begin_layout Itemize
2688 sx: number: The x-coordinate in source.
2691 \begin_layout Itemize
2692 sy: number: The y-coordinate in source.
2695 \begin_layout Itemize
2696 w: number: The width of area to blit.
2699 \begin_layout Itemize
2700 h: number: The height of area to blit.
2703 \begin_layout Itemize
2704 hscl: number: Horizontal scale factor (integer).
2707 \begin_layout Itemize
2708 vscl: number: Vertical scale factor (integer).
2709 Defaults to the same as <hscl>.
2712 \begin_layout Itemize
2713 ck: number: The color key.
2714 Pixels with this index are not copied.
2718 \begin_layout Itemize
2719 If none is specified, all pixels are copied.
2722 \begin_layout Itemize
2723 If <src> is paletted, this is color index, otherwise it is a color.
2727 \begin_layout Standard
2728 Like DBITMAP:blit, but also scales the copied part of bitmap (using nearest
2729 neighbor) by factor of <hscl>*<vscl>.
2732 \begin_layout Subsubsection
2733 Method blit_porterduff: Blit a bitmap into another with Porter-Duff composition
2736 \begin_layout Itemize
2737 Syntax: dest:blit_porterduff(dx, dy, src, sx, sy, w, h, operator)
2740 \begin_layout Itemize
2741 Syntax: dest:blit_porterduff(dx, dy, src, srcpal, sx, sy, w, h, operator)
2744 \begin_layout Itemize
2745 Deprecated: gui.bitmap_blit_porterduff(dest, ...)
2748 \begin_layout Standard
2752 \begin_layout Itemize
2753 dest: DBITMAP: The target bitmap to blit to.
2756 \begin_layout Itemize
2757 dx: number: The x-coordinate in target.
2760 \begin_layout Itemize
2761 dy: number: The y-coordinate in target.
2764 \begin_layout Itemize
2765 src: BITMAP/DBITMAP: The source bitmap.
2768 \begin_layout Itemize
2769 srcpal: PALETTE: If <src> is indexed, this is the palette for source.
2772 \begin_layout Itemize
2773 sx: number: The x-coordinate in source.
2776 \begin_layout Itemize
2777 sy: number: The y-coordinate in source.
2780 \begin_layout Itemize
2781 w: number: The width of area to blit.
2784 \begin_layout Itemize
2785 h: number: The height of area to blit.
2788 \begin_layout Itemize
2789 operator: string: The operator to use.
2793 \begin_layout Itemize
2794 Can be one of: Src, Atop, Over, In, Out, Dest, DestAtop, DestOver, DestIn,
2795 DestOut, Clear or Xor.
2799 \begin_layout Standard
2800 Like DBITMAP:blit, but instead of just overwriting, applies specified Porter-Duf
2805 \begin_layout Itemize
2806 In target, fully transparent is background.
2807 In source, either fully transparent (if direct) or index 0 (if paletted)
2808 is treated as background.
2811 \begin_layout Subsubsection
2812 Method blit_scaled_porterduff: Blit a bitmap into another with scaling and
2813 Porter-Duff composition
2816 \begin_layout Itemize
2817 Syntax: dest:blit_scaled_porterduff(dx, dy, src, sx, sy, w, h, hscl, [vscl],
2821 \begin_layout Itemize
2822 Syntax: dest:blit_scaled_porterduff(dx, dy, src, srcpal, sx, sy, w, h, hscl,
2826 \begin_layout Itemize
2827 Deprecated: gui.bitmap_blit_scaled_porterduff(dest, ...)
2830 \begin_layout Standard
2834 \begin_layout Itemize
2835 dest: DBITMAP: The target bitmap to blit to.
2838 \begin_layout Itemize
2839 dx: number: The x-coordinate in target.
2842 \begin_layout Itemize
2843 dy: number: The y-coordinate in target.
2846 \begin_layout Itemize
2847 src: BITMAP/DBITMAP: The source bitmap.
2850 \begin_layout Itemize
2851 srcpal: PALETTE: If <src> is indexed, this is the palette for source.
2854 \begin_layout Itemize
2855 sx: number: The x-coordinate in source.
2858 \begin_layout Itemize
2859 sy: number: The y-coordinate in source.
2862 \begin_layout Itemize
2863 w: number: The width of area to blit.
2866 \begin_layout Itemize
2867 h: number: The height of area to blit.
2870 \begin_layout Itemize
2871 hscl: number: Horizontal scale factor (integer).
2874 \begin_layout Itemize
2875 vscl: number: Vertical scale factor (integer).
2876 Defaults to the same as <hscl>.
2879 \begin_layout Itemize
2880 operator: string: The operator to use.
2884 \begin_layout Itemize
2885 Can be one of: Src, Atop, Over, In, Out, Dest, DestAtop, DestOver, DestIn,
2886 DestOut, Clear or Xor.
2890 \begin_layout Standard
2891 Like DBITMAP:blit_porterduff, but also scales the source by <hscl>*<vscl>
2892 like DBITMAP:blit_scaled.
2895 \begin_layout Subsubsection
2896 Method adjust_transparency: Adjust transparency of bitmap
2899 \begin_layout Itemize
2900 Syntax: bitmap:adjust_transparency(newvalue)
2903 \begin_layout Itemize
2904 Deprecated: gui.adjust_transparency(bitmap, ...)
2907 \begin_layout Standard
2911 \begin_layout Itemize
2912 bitmap: DBITMAP: The bitmap to adjust.
2915 \begin_layout Itemize
2916 Number adj: The factor to multiply opaqueness with times 256.
2919 \begin_layout Standard
2920 Multiply opaqueness of all colors in bitmap <bitmap> by factor of <adj>/256.
2923 \begin_layout Subsubsection
2924 Method save_png: Save a bitmap to PNG
2927 \begin_layout Itemize
2928 Syntax: bitmap:save_png(filename, [base])
2931 \begin_layout Itemize
2932 Syntax: data bitmap:save_png()
2935 \begin_layout Itemize
2937 gui.bitmap_save_png(bitmap, ...)
2940 \begin_layout Standard
2944 \begin_layout Itemize
2945 bitmap: DBITMAP: The bitmap to save.
2948 \begin_layout Itemize
2949 filename: string: The filename to save to.
2952 \begin_layout Itemize
2953 base: string: The base filename is resolved relative to.
2956 \begin_layout Standard
2960 \begin_layout Itemize
2961 data: string: BASE64 encoded PNG data.
2964 \begin_layout Standard
2965 Save bitmap <bitmap> into PNG file <filename> (relative to <base>) or return
2966 BASE64 encoding of it.
2969 \begin_layout Subsubsection
2970 Method hash: Hash a bitmap
2973 \begin_layout Itemize
2974 Syntax: hash bitmap:hash()
2977 \begin_layout Itemize
2978 Deprecated: hash bitmap:hash(bitmap)
2981 \begin_layout Standard
2985 \begin_layout Itemize
2986 bitmap: DBITMAP: The bitmap to hash.
2989 \begin_layout Standard
2993 \begin_layout Itemize
2994 hash: string: 64-hex digit hash
2997 \begin_layout Standard
2998 Hashes bitmap <bitmap> and returns crypto-strong hash.
3002 \begin_layout Subsection
3003 IMAGELOADER: Load an image
3006 \begin_layout Subsubsection
3007 Static function load: Load a bitmap from file
3010 \begin_layout Itemize
3011 Syntax: bitmap, palette gui.image.load(file, [base])
3014 \begin_layout Itemize
3015 Syntax: bitmap, palette classes.IMAGELOADER.load(file, [base])
3018 \begin_layout Itemize
3020 gui.bitmap_load(...)
3023 \begin_layout Standard
3027 \begin_layout Itemize
3028 file: string: The file to read.
3031 \begin_layout Itemize
3032 base: string: The base to resolve <file> relative to.
3035 \begin_layout Standard
3039 \begin_layout Itemize
3040 bitmap: BITMAP/DBITMAP: The new bitmap
3043 \begin_layout Itemize
3044 palette: PALETTE: If bitmap is paletted, this is the palette, otherwise
3048 \begin_layout Standard
3049 Load a new bitmap and return it (plus associated palette if any).
3052 \begin_layout Subsubsection
3053 Static function load_str: Load a bitmap from string
3056 \begin_layout Itemize
3057 Syntax: bitmap, palette gui.image.load_str(data)
3060 \begin_layout Itemize
3061 Syntax: bitmap, palette classes.IMAGELOADER.load_str(data)
3064 \begin_layout Itemize
3066 gui.bitmap_load_str(...)
3069 \begin_layout Standard
3073 \begin_layout Itemize
3074 data: string: The image data
3077 \begin_layout Standard
3081 \begin_layout Itemize
3082 bitmap: BITMAP/DBITMAP: The new bitmap
3085 \begin_layout Itemize
3086 palette: PALETTE: If bitmap is paletted, this is the palette, otherwise
3090 \begin_layout Standard
3091 Like IMAGELOADER:load, but read the bitmap from string <data> instead of
3095 \begin_layout Subsubsection
3096 Static function load_png: Load a bitmap from PNG file
3099 \begin_layout Itemize
3100 Syntax: bitmap, palette gui.image.load_png(file, [base])
3103 \begin_layout Itemize
3104 Syntax: bitmap, palette classes.IMAGELOADER.load_png(file, [base])
3107 \begin_layout Itemize
3109 gui.bitmap_load_png(...)
3112 \begin_layout Standard
3116 \begin_layout Itemize
3117 file: string: The file to read.
3120 \begin_layout Itemize
3121 base: string: The base to resolve <file> relative to.
3124 \begin_layout Standard
3128 \begin_layout Itemize
3129 bitmap: BITMAP/DBITMAP: The new bitmap
3132 \begin_layout Itemize
3133 palette: PALETTE: If bitmap is paletted, this is the palette, otherwise
3137 \begin_layout Standard
3138 Like IMAGELOADER:load, but load a PNG file instead.
3141 \begin_layout Subsubsection
3142 Static function load_png_str: Load a PNG bitmap from string
3145 \begin_layout Itemize
3146 Syntax: bitmap, palette gui.image.load_png_str(data)
3149 \begin_layout Itemize
3150 Syntax: bitmap, palette classes.IMAGELOADER.load_png_str(data)
3153 \begin_layout Itemize
3155 gui.bitmap_load_png_str(...)
3158 \begin_layout Standard
3162 \begin_layout Itemize
3163 data: string: The image data, base64 encoded.
3166 \begin_layout Standard
3170 \begin_layout Itemize
3171 bitmap: BITMAP/DBITMAP: The new bitmap
3174 \begin_layout Itemize
3175 palette: PALETTE: If bitmap is paletted, this is the palette, otherwise
3179 \begin_layout Standard
3180 Like IMAGELOADER:load_png, but read the bitmap from BASE64 encoded string
3181 <data> instead of file.
3184 \begin_layout Standard
3185 \begin_inset Newpage pagebreak
3191 \begin_layout Subsection
3192 CUSTOMFONT: Arbitrary-sized bitmap font
3195 \begin_layout Subsubsection
3196 Static function new: Return a new empty font
3199 \begin_layout Itemize
3200 Syntax: font gui.font.new()
3203 \begin_layout Itemize
3204 Syntax: font classes.CUSTOMFONT.new()
3207 \begin_layout Itemize
3208 Deprecated: font gui.font_new()
3211 \begin_layout Standard
3215 \begin_layout Itemize
3216 font: CUSTOMFONT: New font.
3219 \begin_layout Standard
3220 Create a new font with no characters and return it.
3223 \begin_layout Subsubsection
3224 Static function: load: Load a font file
3227 \begin_layout Itemize
3228 Syntax: font gui.font.load(file, [base])
3231 \begin_layout Itemize
3232 Syntax: font gui.font.load()
3235 \begin_layout Itemize
3236 Syntax: font classes.CUSTOMFONT.load(file, [base])
3239 \begin_layout Itemize
3240 Syntax: font classes.CUSTOMFONT.load()
3243 \begin_layout Itemize
3244 Deprecated: font gui.loadfont(...)
3247 \begin_layout Standard
3251 \begin_layout Itemize
3252 file: string: The file to read the font from
3255 \begin_layout Itemize
3256 base: string: The file to resolve <file> relative to.
3259 \begin_layout Standard
3263 \begin_layout Itemize
3264 font: CUSTOMFONT: New font.
3267 \begin_layout Standard
3268 Load font from file <file> (relative to <base>).
3269 If no filename is given, system default font is loaded.
3272 \begin_layout Subsubsection
3273 operator(): Render text to screen
3276 \begin_layout Itemize
3277 Syntax: font(x, y, text, [fgc], [bgc], [hlc])
3280 \begin_layout Standard
3284 \begin_layout Itemize
3285 font: CUSTOMFONT: The font to use.
3288 \begin_layout Itemize
3289 x: number: The x-position on screen to draw to.
3292 \begin_layout Itemize
3293 y: number: The y-position on screen to draw to.
3296 \begin_layout Itemize
3297 text: string: The text to draw.
3300 \begin_layout Itemize
3301 fgc: number/string: Foreground color (default white).
3304 \begin_layout Itemize
3305 bgc: number/string: Background color (default transparent).
3308 \begin_layout Itemize
3309 hlc: number/string: Outline color (default transparent).
3312 \begin_layout Standard
3313 Draws a string <text> with specified font <font> and colors <fgc>,<bgc>,<hlc>
3317 \begin_layout Itemize
3318 If <hlc> is transparent, no outline is drawn.
3321 \begin_layout Subsubsection
3322 Method edit: Alter glyph in font
3325 \begin_layout Itemize
3326 Syntax: font:edit(character, glyph)
3329 \begin_layout Standard
3333 \begin_layout Itemize
3334 font: CUSTOMFONT: The font to edit.
3337 \begin_layout Itemize
3338 character: string: The character to edit (UTF-8 encoded).
3341 \begin_layout Itemize
3342 glyph: BITMAP: The bitmap to use.
3345 \begin_layout Standard
3346 Replace character <character> in font <font> by <glyph>.
3349 \begin_layout Itemize
3350 Color index 0 is background, everything else is foreground.
3353 \begin_layout Itemize
3354 <character> may be empty string, meaning the replacement character used
3358 \begin_layout Itemize
3359 <character> may be multi-codepoint string, meaning character used for that
3363 \begin_layout Standard
3364 \begin_inset Newpage pagebreak
3370 \begin_layout Subsection
3371 ICONV: Character set conversions
3374 \begin_layout Subsubsection
3375 Static function new: Create new character set converter
3378 \begin_layout Itemize
3379 Syntax: iconv iconv.new(from, to);
3382 \begin_layout Itemize
3383 Syntax: iconv classes.ICONV.new(from, to);
3386 \begin_layout Itemize
3387 Deprecated: iconv iconv_new(...);
3390 \begin_layout Standard
3394 \begin_layout Itemize
3395 from: string: The source character set.
3398 \begin_layout Itemize
3399 to: string: The target character set.
3402 \begin_layout Standard
3406 \begin_layout Itemize
3407 iconv: ICONV: The converter.
3410 \begin_layout Standard
3411 Create a character set converter, converting from <from> to <to> and return
3415 \begin_layout Subsubsection
3416 Operator(): Convert string fragment from character set to another
3419 \begin_layout Itemize
3420 Syntax: success, result, unconverted, error iconv(input)
3423 \begin_layout Standard
3427 \begin_layout Itemize
3428 iconv: ICONV: The context to use.
3431 \begin_layout Itemize
3432 input: string: The input to convert.
3435 \begin_layout Standard
3439 \begin_layout Itemize
3440 success: boolean: True if conversion was successful, false if not.
3443 \begin_layout Itemize
3444 result: string: The string (partially) converted.
3447 \begin_layout Itemize
3448 unconvered: number: Number of bytes that were not converted (only if <success>
3452 \begin_layout Itemize
3453 error: string: Error that caused conversion to stop (only if <success> is
3458 \begin_layout Itemize
3459 INVALID: The input string is invalid.
3462 \begin_layout Itemize
3463 INCOMPLETE: The input string cuts off in middle of character.
3466 \begin_layout Itemize
3467 INTERNALERR: Internal error.
3471 \begin_layout Standard
3472 Convert a string <input> using character set converter <iconv> and return
3476 \begin_layout Standard
3477 \begin_inset Newpage pagebreak
3483 \begin_layout Subsection
3484 FILEREADER: Read a file as a stream
3487 \begin_layout Subsubsection
3488 Static function open: Open a stream
3491 \begin_layout Itemize
3492 Syntax: handle filereader.open(file, [base])
3495 \begin_layout Itemize
3496 Syntax: handle classes.FILEREADER.open(file, [base])
3499 \begin_layout Itemize
3500 Deprecated: handle open_file(file, [base])
3503 \begin_layout Standard
3507 \begin_layout Itemize
3508 file: string: The filename to read.
3511 \begin_layout Itemize
3512 base: string: The base <file> is resolved against.
3515 \begin_layout Standard
3519 \begin_layout Itemize
3520 handle: FILEREADER: The new file reader.
3523 \begin_layout Standard
3524 Open file <file> (relative to <base>) and return a handle to it.
3527 \begin_layout Subsubsection
3528 operator(): Read line/bytes from stream
3531 \begin_layout Itemize
3532 Syntax: result handle()
3535 \begin_layout Itemize
3536 Syntax: result handle(bytes)
3539 \begin_layout Standard
3543 \begin_layout Itemize
3544 handle: FILEREADER: The handle to read from.
3547 \begin_layout Itemize
3548 bytes: Number of bytes to read (default is next line).
3551 \begin_layout Standard
3555 \begin_layout Itemize
3556 result: string: The read data, or nil on end-of-file.
3559 \begin_layout Standard
3560 Reads next line or <bytes> bytes from specified file handle <handle>.
3563 \begin_layout Itemize
3564 If reading specified number of bytes, the bytes are read in binary mode
3568 \begin_layout Itemize
3569 If reading next line, the line is read in text mode (any line ending is
3573 \begin_layout Subsubsection
3574 Method lines: Iterator to read all lines
3577 \begin_layout Itemize
3578 Syntax: for line in handle:lines() do ...
3582 \begin_layout Standard
3586 \begin_layout Itemize
3587 handle: FILEREADER: The handle to read.
3590 \begin_layout Standard
3594 \begin_layout Itemize
3595 A lua iterator with one variable.
3598 \begin_layout Standard
3599 Return a Lua iterator that iterates all the lines in <handle>.
3602 \begin_layout Standard
3603 \begin_inset Newpage pagebreak
3609 \begin_layout Subsection
3610 COMPARE_OBJ: Watch memory area for changes
3613 \begin_layout Standard
3614 Objects of this class allow fast checking for modifications to given memory
3618 \begin_layout Subsubsection
3619 Static function new: Create a checker
3622 \begin_layout Itemize
3623 Syntax: handle classes.COMPARE_OBJ.new({marea, offset|addrobj}, size, [rows,
3627 \begin_layout Itemize
3628 Syntax: handle memory.compare_new({marea, offset|addrobj}, size, rows, stride)
3631 \begin_layout Standard
3635 \begin_layout Itemize
3636 marea: string: The memory area to interpret <offset> against.
3639 \begin_layout Itemize
3640 offset: number: The initial offset in memory area.
3643 \begin_layout Itemize
3644 addrobj: ADDRESS: The memory address.
3647 \begin_layout Itemize
3648 size: number: The number of bytes in each row.
3651 \begin_layout Itemize
3652 rows: number: The number of rows.
3656 \begin_layout Itemize
3657 stride: number: The number of bytes offset increments from one row to next.
3660 \begin_layout Standard
3664 \begin_layout Itemize
3668 \begin_layout Standard
3669 Return an object watching specified memory area.
3672 \begin_layout Itemize
3673 Note: For fastest operation, limit checks to inside one memory area (that
3674 has to be mappable, individual RAM areas often are).
3677 \begin_layout Subsubsection
3678 operator(): Check area for modifications
3681 \begin_layout Itemize
3682 Syntax: boolean handle()
3685 \begin_layout Standard
3689 \begin_layout Itemize
3690 True if memory block has been modified since last call (or object creation
3691 if first call), false if not.
3694 \begin_layout Standard
3695 Check if the block has been modified.
3698 \begin_layout Subsection
3699 ADDRESS: Memory address
3702 \begin_layout Standard
3703 Objects of this class contain a memory address.
3706 \begin_layout Subsubsection
3707 Static function new: Create new memory address
3710 \begin_layout Itemize
3711 Syntax: ADDRESS classes.ADDRESS.new(string marea, number offset)
3714 \begin_layout Itemize
3715 Syntax: ADDRESS memory.address.new(string marea, number offset)
3718 \begin_layout Itemize
3719 Syntax: ADDRESS memory.mkaddr(string marea, number offset)
3722 \begin_layout Standard
3726 \begin_layout Itemize
3727 marea: The memory area
3730 \begin_layout Itemize
3731 offset: The offset in memory area.
3734 \begin_layout Standard
3738 \begin_layout Itemize
3742 \begin_layout Standard
3743 Construct a new memory address object.
3746 \begin_layout Subsubsection
3747 Method: addr: Get global address
3750 \begin_layout Itemize
3751 Syntax: number addr:addr()
3754 \begin_layout Standard
3758 \begin_layout Itemize
3759 addr: ADRESS: The original address.
3762 \begin_layout Standard
3766 \begin_layout Itemize
3767 The global address corresponding to this address.
3770 \begin_layout Subsubsection
3771 Method: vma: Get memory area
3774 \begin_layout Itemize
3775 Syntax: string addr:vma()
3778 \begin_layout Standard
3782 \begin_layout Itemize
3783 addr: ADRESS: The original address.
3786 \begin_layout Standard
3790 \begin_layout Itemize
3791 The memory area corresponding to this address.
3794 \begin_layout Subsubsection
3795 Method: offset: Get memory area offset
3798 \begin_layout Itemize
3799 Syntax: string addr:offset()
3802 \begin_layout Standard
3806 \begin_layout Itemize
3807 addr: ADRESS: The original address.
3810 \begin_layout Standard
3814 \begin_layout Itemize
3815 The offset in memory area corresponding to this address.
3818 \begin_layout Subsubsection
3819 Method: replace: Replace address part
3822 \begin_layout Itemize
3823 Syntax: ADDRESS addr:replace(offset[, bits])
3826 \begin_layout Standard
3830 \begin_layout Itemize
3831 addr: ADRESS: The original address.
3834 \begin_layout Itemize
3835 offset: number: The new offset
3838 \begin_layout Itemize
3839 bits: number: The number of LSB to replace.
3842 \begin_layout Standard
3846 \begin_layout Itemize
3847 The modified address
3850 \begin_layout Standard
3851 Returns a new address, with <bits> (all if missing) least significant bits
3852 of <addr> replaced by LSB of <offset>.
3855 \begin_layout Subsubsection
3856 Method: add: Add to address
3859 \begin_layout Itemize
3860 Syntax: ADDRESS addr:add(offset)
3863 \begin_layout Itemize
3864 Syntax: ADDRESS addr:add(number, stride)
3867 \begin_layout Itemize
3868 Syntax: ADDRESS addr:add(number, stride, offset)
3871 \begin_layout Standard
3875 \begin_layout Itemize
3876 addr: ADRESS: The original address.
3879 \begin_layout Itemize
3880 offset: number: Offset to add.
3883 \begin_layout Itemize
3884 number: number: Number of table strides to add.
3887 \begin_layout Itemize
3888 stride: number: The table stride.
3891 \begin_layout Standard
3895 \begin_layout Itemize
3896 The modified address
3899 \begin_layout Standard
3900 Adds <offset>, <number>*<stride> or <number>*<stride>+<offset> into specified
3904 \begin_layout Subsection
3905 ADDRESS:<op>: Read/Write memory
3908 \begin_layout Itemize
3909 Syntax: none addr:<op>(value)
3912 \begin_layout Itemize
3913 Syntax: number addr:<op>()
3916 \begin_layout Standard
3920 \begin_layout Itemize
3921 addr: ADDRESS: The address to read/write.
3924 \begin_layout Itemize
3925 value: number: The number to write.
3928 \begin_layout Standard
3932 \begin_layout Itemize
3936 \begin_layout Standard
3937 Read/Write value from/to given address <addr>.
3938 The value written is <value>.
3939 <Op> is of form: [i][s]<type>, where:
3942 \begin_layout Itemize
3943 <type> is one of 'byte', 'word', 'hword', 'dword', 'qword', 'float', 'double'.
3946 \begin_layout Itemize
3947 'i' signifies that the value is treated as opposite-to-normal endianess,
3950 \begin_layout Itemize
3951 's' signifies that value is treated as signed (not available for floating-point).
3954 \begin_layout Standard
3955 \begin_inset Newpage pagebreak
3961 \begin_layout Section
3965 \begin_layout Subsection
3966 print: Print values to console
3969 \begin_layout Itemize
3970 Syntax: none print(value...
3974 \begin_layout Standard
3975 Prints specified values to console.
3976 Can print any Lua type at least enough to identify the type and instance.
3979 \begin_layout Subsection
3980 tostringx: Format a value to string
3983 \begin_layout Itemize
3984 Syntax: string tostringx(value val)
3987 \begin_layout Standard
3988 Formats value <val> like print would, and returns the result as a string.
3991 \begin_layout Subsection
3992 exec: Execute lsnes commands
3995 \begin_layout Itemize
3996 Syntax: none exec(string cmd)
3999 \begin_layout Standard
4000 Execute lsnes command <cmd>.
4003 \begin_layout Subsection
4004 utime: Get current time
4007 \begin_layout Itemize
4008 Syntax: (number,number) utime()
4011 \begin_layout Standard
4012 Returns two numbers.
4013 First is time since some epoch in seconds, the second is microseconds mod
4014 10^6 since that epoch.
4017 \begin_layout Subsection
4018 set_idle_timeout: Run function after timeout when emulator is idle
4021 \begin_layout Itemize
4022 Syntax: none set_idle_timeout(number timeout)
4025 \begin_layout Standard
4026 Set number of microseconds to block idle for.
4027 After this timeout has expired, on_idle() will be called once.
4030 \begin_layout Subsection
4031 set_timer_timeout: Run function after timeout.
4034 \begin_layout Itemize
4035 Syntax: none set_timer_timeout(number timeout)
4038 \begin_layout Standard
4039 Set number of microseconds to block timer for.
4040 After this timeout has expired, on_timer() will be called once.
4043 \begin_layout Subsection
4044 bus_address: Look up address in system bus.
4047 \begin_layout Itemize
4048 Syntax: none bus_address(number bus_addr)
4051 \begin_layout Standard
4052 Returns virtual address corresponding to specified address on system bus.
4055 \begin_layout Subsection
4056 loopwrapper: Convert loop into callable function
4059 \begin_layout Itemize
4060 Syntax: function loopwrapper(function fun, ...)
4063 \begin_layout Standard
4064 Calls function <fun> with function and specified arguments.
4065 The function passed suspends execution until the function returned is called.
4066 Handy for linear flow control among multiple invocations of a hook.
4070 \begin_layout LyX-Code
4071 on_paint = loopwrapper(function(wait)
4075 \begin_layout LyX-Code
4080 \begin_layout LyX-Code
4082 \begin_inset Quotes eld
4086 \begin_inset Quotes erd
4092 \begin_layout LyX-Code
4097 \begin_layout LyX-Code
4102 \begin_layout LyX-Code
4106 \begin_layout Subsection
4107 list_bindings: List keybindings
4110 \begin_layout Itemize
4111 Syntax: table list_bindings([string cmd])
4114 \begin_layout Standard
4115 Get table of all keybindings, indexed by keyspec (modifiers|mask/key).
4116 If <cmd> is specified, the table is limited to that command.
4117 Also searches for controller keys.
4120 \begin_layout Subsection
4121 get_alias: Get expansion of alias
4124 \begin_layout Itemize
4125 Syntax: string get_alias(string aname)
4128 \begin_layout Standard
4129 Get expansion of given alias <aname>.
4132 \begin_layout Subsection
4133 set_alias: Set expansion of alias
4136 \begin_layout Itemize
4137 Syntax: none set_alias(string aname, string value)
4140 \begin_layout Standard
4141 Set expansion of given alias.
4144 \begin_layout Subsection
4145 create_ibind: Create invese binding
4148 \begin_layout Itemize
4149 Syntax: INVERSEBIND create_ibind(string name, string cmd)
4152 \begin_layout Standard
4153 Return object representing inverse binding with specified name <name> and
4154 specified command <cmd>.
4157 \begin_layout Itemize
4158 Note: To create press/release commands, use aliases +foo and -foo .
4161 \begin_layout Itemize
4162 Note: Keep the returned object around.
4165 \begin_layout Subsection
4166 create_command: Create a command
4169 \begin_layout Itemize
4170 Syntax: COMMANDBIND create_commmand(string name, function a)
4173 \begin_layout Itemize
4174 Syntax: COMMANDBIND create_commmand(string name, function a, function b)
4177 \begin_layout Standard
4178 Return object representing a command (pair).
4181 \begin_layout Itemize
4182 If only one function is specied, the command is level-sensitive, <a> is
4186 \begin_layout Itemize
4187 If <b> is function, the function is edge-sensitive, <a> is positive edge
4188 callback and <b> is negative edge callback.
4191 \begin_layout Itemize
4192 All callbacks get single argument: The parameters passed.
4195 \begin_layout Itemize
4196 Keep the returned object around.
4199 \begin_layout Subsection
4200 loadfile: Load Lua script
4203 \begin_layout Itemize
4204 Syntax: function loadfile(string filename[, string base])
4207 \begin_layout Standard
4208 Load lua script from <filename>, resolved relative to <base> (if empty,
4212 \begin_layout Subsection
4213 dofile: Execute Lua script
4216 \begin_layout Itemize
4217 Syntax: function dofile(string filename[, string base])
4220 \begin_layout Standard
4221 Execute lua script from <filename>, resolved relative to <base> (if empty,
4222 current directory) and return all return values.
4225 \begin_layout Subsection
4226 resolve_filename: Resolve name of file relative to another
4229 \begin_layout Itemize
4230 Syntax: string resolve_file(string filename, string base)
4233 \begin_layout Standard
4234 Resolve name of file <filename> relative to <base> and return the result.
4237 \begin_layout Subsection
4238 render_queue_function: Return paint function for render queue
4241 \begin_layout Itemize
4242 Syntax: function render_queue_function(RENDERQUEUE rq)
4245 \begin_layout Standard
4246 Return function that renders render queue <rq>.
4249 \begin_layout Itemize
4250 Handy for paint callback if one is using render queues updated in other
4255 \begin_layout LyX-Code
4256 handle = callback.paint:register(render_queue_function(my_rq));
4259 \begin_layout Subsection
4260 identify_class: Identify class of object
4263 \begin_layout Itemize
4264 Syntax: string identify_class(userdata object)
4267 \begin_layout Standard
4268 Identifies the class of userdata <object>, if possible.
4269 If no identification is possible, returns
4270 \begin_inset Quotes eld
4274 \begin_inset Quotes erd
4280 \begin_layout Subsection
4281 lookup_class: Lookup class by name
4284 \begin_layout Itemize
4285 Syntax: classobj lookup_class(string name)
4288 \begin_layout Standard
4289 Looks up class corresponding to <name>, if possible.
4290 If not found, returns nil.
4291 The classobj has following fields:
4294 \begin_layout Itemize
4295 _static_methods: Return static method names
4298 \begin_layout Itemize
4299 _class_methods: Return class method names
4302 \begin_layout Itemize
4303 <static-function-name>: The specified static function.
4306 \begin_layout Subsection
4307 all_classes: Get list of all classes
4310 \begin_layout Itemize
4315 \begin_layout Standard
4316 Get names of all classes available.
4319 \begin_layout Subsection
4323 \begin_layout Subsection
4327 \begin_layout Standard
4331 \begin_layout Subsection
4332 filereader: Class FILEREADER
4335 \begin_layout Standard
4336 See class FILEREADER.
4339 \begin_layout Standard
4340 \begin_inset Newpage pagebreak
4346 \begin_layout Section
4350 \begin_layout Standard
4351 Bitwise logical functions and related.
4354 \begin_layout Subsection
4355 bit.none/bit.bnot: Bitwise none or NOT function
4358 \begin_layout Itemize
4359 Syntax: number bit.none(number...)
4362 \begin_layout Itemize
4363 Syntax: number bit.bnot(number...)
4366 \begin_layout Standard
4367 48-bit bitwise NOT / NONE function (set bits that are set in none of the
4371 \begin_layout Subsection
4372 bit.any/bit.bor: Bitwise any or OR function
4375 \begin_layout Itemize
4376 Syntax: number bit.any(number...)
4379 \begin_layout Itemize
4380 Syntax: number bit.bor(number...)
4383 \begin_layout Standard
4384 48-bit bitwise OR / ANY function (set bits that are set in any of the arguments).
4387 \begin_layout Subsection
4388 bit.all/bit.band: Bitwise all or AND function
4391 \begin_layout Itemize
4392 Syntax: number bit.all(number...)
4395 \begin_layout Itemize
4396 Syntax: number bit.band(number...)
4399 \begin_layout Standard
4400 48-bit bitwise AND / ALL function (set bits that are set in all of the arguments
4404 \begin_layout Subsection
4405 bit.parity/bit.bxor: Bitwise parity or XOR function
4408 \begin_layout Itemize
4409 Syntax: number bit.parity(number...)
4412 \begin_layout Itemize
4413 Syntax: number bit.bxor(number...)
4416 \begin_layout Standard
4417 48-bit bitwise XOR / PARITY function (set bits that are set in odd number
4421 \begin_layout Subsection
4422 bit.lrotate: Rotate a number left
4425 \begin_layout Itemize
4426 Syntax: number bit.lrotate(number base[, number amount[, number bits]])
4429 \begin_layout Standard
4430 Rotate <bits>-bit (max 48, default 48) number <base> left by <amount> (default
4434 \begin_layout Subsection
4435 bit.rrotate: Rotate a number right
4438 \begin_layout Itemize
4439 Syntax: number bit.rrotate(number base[, number amount[, number bits]])
4442 \begin_layout Standard
4443 Rotate <bits>-bit (max 48, default 48) number <base> right by <amount> (default
4447 \begin_layout Subsection
4448 bit.lshift: Shift a number left
4451 \begin_layout Itemize
4452 Syntax: number bit.lshift(number base[, number amount[, number bits]])
4455 \begin_layout Standard
4456 Shift <bits>-bit (max 48, default 48) number <base> left by <amount> (default
4458 The new bits are filled with zeroes.
4461 \begin_layout Subsection
4462 bit.lrshift: Shift a number right (logical)
4465 \begin_layout Itemize
4466 Syntax: number bit.lrshift(number base[, number amount[, number bits]])
4469 \begin_layout Standard
4470 Shift <bits>-bit (max 48, default 48) number <base> logically right by <amount>
4472 The new bits are filled with zeroes.
4475 \begin_layout Subsection
4476 bit.arshift: Shift a number right (arithmetic)
4479 \begin_layout Itemize
4480 Syntax: number bit.arshift(number base[, number amount[, number bits]])
4483 \begin_layout Standard
4484 Shift <bits>-bit (max 48, default 48) number <base> logically right by <amount>
4486 The new bits are shifted in with copy of the high bit.
4489 \begin_layout Subsection
4490 bit.extract: Extract/shuffle bits from number
4493 \begin_layout Itemize
4494 Syntax: number bit.extract(number base[, number bit0[, number bit1,...]])
4497 \begin_layout Standard
4498 Returns number that has bit0-th bit as bit 0, bit1-th bit as 1 and so on.
4501 \begin_layout Itemize
4502 Note: Bit numbers up to 51 should work reliably (then things start falling
4503 apart due to double precision issues).
4506 \begin_layout Itemize
4507 Note: There are two special bit positions, true and false, standing for
4508 always set bit and always clear bit.
4511 \begin_layout Subsection
4512 bit.value: Construct number with specified bits set
4515 \begin_layout Itemize
4516 Syntax: number bit.value([number bit1[, number bit2,...]])
4519 \begin_layout Standard
4520 Returns bitwise OR of 1 left shifted by <bit1> places, 1 left shifted by
4521 <bit2> places and so on.
4522 As special value, nil argument is no-op.
4525 \begin_layout Subsection
4526 bit.test: Test if bit is set
4529 \begin_layout Itemize
4530 Syntax: boolean bit.test(number a, number bit)
4533 \begin_layout Standard
4534 Tests if bit <bit> is set in <a>.
4535 If it is set, returns true, otherwise false.
4538 \begin_layout Subsection
4539 bit.testn: Test if bit is clear
4542 \begin_layout Itemize
4543 Syntax: boolean bit.testn(number a, number bit)
4546 \begin_layout Standard
4547 Tests if bit <bit> is set in <a>.
4548 If it is clear, returns true, otherwise false.
4551 \begin_layout Subsection
4552 bit.test_any: Test if any bit is set
4555 \begin_layout Itemize
4556 Syntax: boolean bit.test_any(number a, number b)
4559 \begin_layout Standard
4560 Returns true if bitwise and of <a> and <b> is nonzero, otherwise false.
4563 \begin_layout Subsection
4564 bit.test_all: Test if all bits are set
4567 \begin_layout Itemize
4568 Syntax: boolean bit.test_all(number a, number b)
4571 \begin_layout Standard
4572 Returns true if bitwise and of <a> and <b> equals <b>, otherwise false.
4575 \begin_layout Subsection
4576 bit.popcount: Population count
4579 \begin_layout Itemize
4580 Syntax: number bit.popcount(number a)
4583 \begin_layout Standard
4584 Returns number of set bits in <a>.
4587 \begin_layout Subsection
4588 bit.clshift: Chained left shift
4591 \begin_layout Itemize
4592 Syntax: (number, number) bit.clshift(number a, number b, [number amount,[number
4596 \begin_layout Standard
4597 Does chained left shift on <a>, <b> by <amount> positions (default 1), assuming
4598 numbers to be of specified number of bits <bits> (default 48).
4601 \begin_layout Subsection
4602 bit.crshift: Chained right shift
4605 \begin_layout Itemize
4606 Syntax: (number, number) bit.crshift(number a, number b, [number amount,[number
4610 \begin_layout Standard
4611 Does chained right shift on <a>, <b> by <amount> positions (default 1),
4612 assuming numbers to be of specified number of bits <bits> (default 48).
4615 \begin_layout Subsection
4616 bit.flagdecode: Decode bitfield into flags
4619 \begin_layout Itemize
4620 Syntax: string bit.flagdecode(number a, number bits, [string on, [string
4624 \begin_layout Standard
4625 Return string of length bits where ith character is ith character of on
4626 if bit i is on, otherwise ith character of off.
4627 Out of range reads give last character.
4630 \begin_layout Itemize
4631 Note: <on> defaults to '*' if empty.
4634 \begin_layout Itemize
4635 Note: <off> defaults to '-' if empty.
4638 \begin_layout Subsection
4639 bit.rflagdecode: Decode bitfield into flags
4642 \begin_layout Itemize
4643 Syntax: string bit.rflagdecode(number a, number bits, [string on, [string
4647 \begin_layout Standard
4648 Like bit.flagdecode, but outputs the string in the opposite order (most significa
4652 \begin_layout Subsection
4653 bit.swap{,s}{,h,d,q}word: Swap word endian
4656 \begin_layout Itemize
4657 Syntax: number bit.swapword(number n)
4660 \begin_layout Itemize
4661 Syntax: number bit.swaphword(number n)
4664 \begin_layout Itemize
4665 Syntax: number bit.swapdword(number n)
4668 \begin_layout Itemize
4669 Syntax: number bit.swapqword(number n)
4672 \begin_layout Itemize
4673 Syntax: number bit.swapsword(number n)
4676 \begin_layout Itemize
4677 Syntax: number bit.swapshword(number n)
4680 \begin_layout Itemize
4681 Syntax: number bit.swapsdword(number n)
4684 \begin_layout Itemize
4685 Syntax: number bit.swapsqword(number n)
4688 \begin_layout Standard
4689 Swap endianess of (un)signed integer <n>.
4692 \begin_layout Subsection
4693 bit.compose: Compose multi-byte number
4696 \begin_layout Itemize
4697 Syntax: number bit.compose(number n...)
4700 \begin_layout Standard
4702 \begin_inset Formula $n_{1}+256n_{2}+256^{2}n_{3}+\ldots$
4708 \begin_layout Subsection
4709 bit.binary_ld_{{u,s}{8,16,24,32,64},float,double}{l,b}e: Load binary integer
4712 \begin_layout Itemize
4713 Syntax: number bit.binary_ld_<type>le(string str, number pos);
4716 \begin_layout Itemize
4717 Syntax: number bit.binary_ld_<type>be(string str, number pos);
4720 \begin_layout Standard
4721 Load little (*le) or big (*be) endian binary number from position <pos>
4723 Type may be one of: u8, u16, u24, u32, u64, s8, s16, s24, s32, s64, float,
4727 \begin_layout Subsection
4728 bit.binary_st_{{u,s}{8,16,24,32,64},float,double}{l,b}e: Store binary integer
4731 \begin_layout Itemize
4732 Syntax: string bit.binary_st_<type>le(number x);
4735 \begin_layout Itemize
4736 Syntax: string bit.binary_st_<type>be(number x);
4739 \begin_layout Standard
4740 Store specified number <x> as binary in string and return the result.
4741 Type may be one of: u8, u16, u24, u32, u64, s8, s16, s24, s32, s64, float,
4745 \begin_layout Subsection
4746 bit.quotent: Integer quotent
4749 \begin_layout Itemize
4750 Syntax: number bit.quotent(number a, number b)
4753 \begin_layout Standard
4754 Calculate quotent a/b.
4757 \begin_layout Subsection
4758 bit.multidiv: Divide and split among multiple divisiors
4761 \begin_layout Itemize
4763 bit.multidiv(number v, number q...)
4766 \begin_layout Standard
4767 Does the following steps:
4770 \begin_layout Enumerate
4774 \begin_layout Enumerate
4779 \begin_layout Enumerate
4780 Calculate quotent(v'/q) and add that to numbers returned.
4783 \begin_layout Enumerate
4784 v' <- remainder(v'/q)
4788 \begin_layout Enumerate
4789 Add v' to numbers returned.
4792 \begin_layout Standard
4793 That is, it successively divides <v> by <q>s, and reduces <v> modulo <q>
4795 <v> may be floating point, <q>s are integers.
4798 \begin_layout Itemize
4800 bit.multidiv(time, 3600, 60) splits time into hours, minutes and seconds.
4803 \begin_layout Itemize
4805 bit.multidiv(a, b) calculates quotent and remainder of a/b.
4808 \begin_layout Subsection
4809 bit.mul32: 32-bit multiply
4812 \begin_layout Itemize
4813 Syntax: number, number bit.mul32(number a, number b)
4816 \begin_layout Standard
4817 Multiply 32-bit numbers <a> and <b>.
4818 The first return value is low 32 bits of result, the second is high 32
4822 \begin_layout Standard
4823 \begin_inset Newpage pagebreak
4829 \begin_layout Section
4833 \begin_layout Subsection
4834 classes.<foo>: The classobj for class <foo>
4837 \begin_layout Itemize
4838 Syntax: classes.<foo>
4841 \begin_layout Standard
4842 The classobj for class <foo>.
4845 \begin_layout Subsection
4846 classes.<foo>._static_methods: Enumerate static methods
4849 \begin_layout Itemize
4851 classes.<foo>._static_methods()
4854 \begin_layout Standard
4855 Returns all static methods of <foo> as strings.
4858 \begin_layout Subsection
4859 classes.<foo>._class_methods: Enumerate static methods
4862 \begin_layout Itemize
4864 classes.<foo>._class_methods()
4867 \begin_layout Standard
4868 Returns all class methods of <foo> as strings.
4871 \begin_layout Subsection
4872 classes.<foo>.<bar>: Static method
4875 \begin_layout Itemize
4876 Syntax: variable classes.<foo>.<bar>(variable...)
4879 \begin_layout Standard
4880 Invokes static method <bar> of class <foo>.
4883 \begin_layout Section
4887 \begin_layout Subsection
4888 gui.resolution: Get current resolution
4891 \begin_layout Itemize
4892 Syntax: (number, number) gui.resolution()
4895 \begin_layout Standard
4896 Returns 2-tuple (hresolution, vresolution).
4899 \begin_layout Subsection
4900 gui.left_gap/gui.right_gap/gui.top_gap/gui.bottom_gap: Set edge gaps
4903 \begin_layout Itemize
4904 Syntax: number gui.left_gap(number gap)
4907 \begin_layout Itemize
4908 Syntax: number gui.right_gap(number gap)
4911 \begin_layout Itemize
4912 Syntax: number gui.top_gap(number gap)
4915 \begin_layout Itemize
4916 Syntax: number gui.bottom_gap(number gap)
4919 \begin_layout Standard
4920 Set the specified edge gap to specified value <gap> (max gap is 8191).
4921 If successful, old gap is returned.
4924 \begin_layout Subsection
4925 gui.delta_left_gap/gui.delta_right_gap/gui.delta_top_gap/gui.delta_bottom_gap:
4929 \begin_layout Itemize
4930 Syntax: number gui.delta_left_gap(number dgap)
4933 \begin_layout Itemize
4934 Syntax: number gui.delta_right_gap(number dgap)
4937 \begin_layout Itemize
4938 Syntax: number gui.delta_top_gap(number dgap)
4941 \begin_layout Itemize
4942 Syntax: number gui.delta_bottom_gap(number dgap)
4945 \begin_layout Standard
4946 Increase the specified edge gap by specified value <dgap> (max gap is 8191)
4947 and return the old gap (returns nothing on error).
4950 \begin_layout Subsection
4951 gui.text/gui.textH/gui.textV,gui.textHV: Draw text
4954 \begin_layout Itemize
4955 Syntax: none gui.text(number x, number y, string text[, number fgc[, number
4959 \begin_layout Itemize
4960 Syntax: none gui.textH(number x, number y, string text[, number fgc[, number
4964 \begin_layout Itemize
4965 Syntax: none gui.textV(number x, number y, string text[, number fgc[, number
4969 \begin_layout Itemize
4970 Syntax: none gui.textHV(number x, number y, string text[, number fgc[, number
4974 \begin_layout Standard
4975 Draw specified text on the GUI (each character cell is 8 or 16 wide and
4980 \begin_layout Itemize
4981 x: X-coordinate to start the drawing from (and x-coordinate at begining
4985 \begin_layout Itemize
4986 y: Y-coordinate to start the drawing from.
4989 \begin_layout Itemize
4990 text: The text to draw.
4993 \begin_layout Itemize
4994 fgc: Text color (default is 0xFFFFFF (white))
4997 \begin_layout Itemize
4998 bgc: Background color (default is -1 (transparent))
5001 \begin_layout Standard
5002 Note: The H variants draw at double width and V variants draw at double
5006 \begin_layout Subsection
5007 gui.rectangle: Draw a rectangle
5010 \begin_layout Itemize
5011 Syntax: none gui.rectangle(number x, number y, number width, number height[,
5012 number thickness[, number outline[, number fill]]])
5015 \begin_layout Standard
5016 Draw rectangle on the GUI.
5020 \begin_layout Itemize
5021 x: X-coordinate of left edge.
5024 \begin_layout Itemize
5025 y: Y-coordinate of upper edge.
5028 \begin_layout Itemize
5029 width: Width of rectangle.
5032 \begin_layout Itemize
5033 height: Height of rectangle.
5036 \begin_layout Itemize
5037 thickness: Thickness of outline (default is 1).
5040 \begin_layout Itemize
5041 outline: Color of outline (default is 0xFFFFFF (white))
5044 \begin_layout Itemize
5045 fill: Color of fill (default is -1 (transparent))
5048 \begin_layout Subsection
5049 gui.solidrectangle: Draw a solid rectangle
5052 \begin_layout Itemize
5053 Syntax: none gui.rectangle(number x, number y, number width, number height[,
5057 \begin_layout Standard
5058 Draw solid rectangle on the GUI.
5062 \begin_layout Itemize
5063 x: X-coordinate of left edge.
5066 \begin_layout Itemize
5067 y: Y-coordinate of upper edge.
5070 \begin_layout Itemize
5071 width: Width of rectangle.
5074 \begin_layout Itemize
5075 height: Height of rectangle.
5078 \begin_layout Itemize
5079 color: Color of rectangle (default is 0xFFFFFF (white))
5082 \begin_layout Subsection
5083 gui.box: Draw a 3D-effect box
5086 \begin_layout Itemize
5087 Syntax: none gui.box(number x, number y, number width, number height[, number
5088 thickness[, number outline1[,number outline2[, number fill]]]])
5091 \begin_layout Standard
5092 Draw rectangle with 3D effect on the GUI.
5096 \begin_layout Itemize
5097 x: X-coordinate of left edge.
5100 \begin_layout Itemize
5101 y: Y-coordinate of upper edge.
5104 \begin_layout Itemize
5105 width: Width of rectangle.
5108 \begin_layout Itemize
5109 height: Height of rectangle.
5112 \begin_layout Itemize
5113 thickness: Thickness of outline (default is 1).
5116 \begin_layout Itemize
5117 outline1: First color of outline (default is 0xFFFFFF (white))
5120 \begin_layout Itemize
5121 outline2: First color of outline (default is 0x808080 (dark gray))
5124 \begin_layout Itemize
5125 fill: Color of fill (default is 0xC0C0C0 (light grayy))
5128 \begin_layout Subsection
5129 gui.pixel: Draw a single pixel
5132 \begin_layout Itemize
5133 Syntax: none gui.pixel(number x, number y[, number color])
5136 \begin_layout Standard
5137 Draw one pixel on the GUI.
5141 \begin_layout Itemize
5142 x: X-coordinate of the pixel
5145 \begin_layout Itemize
5146 y: Y-coordinate of the pixel
5149 \begin_layout Itemize
5150 color: Color of the pixel (default is 0xFFFFFF (white))
5153 \begin_layout Subsection
5154 gui.crosshair: Draw a crosshair
5157 \begin_layout Itemize
5158 Syntax: none gui.crosshair(number x, number y[, number length[, number color]])
5161 \begin_layout Standard
5166 \begin_layout Itemize
5167 x: X-coordinate of the crosshair
5170 \begin_layout Itemize
5171 y: Y-coordinate of the crosshair
5174 \begin_layout Itemize
5175 length: Length of the crosshair lines (default 10).
5178 \begin_layout Itemize
5179 color: Color of the crosshair (default is 0xFFFFFF (white))
5182 \begin_layout Subsection
5183 gui.line: Draw a line
5186 \begin_layout Itemize
5187 Syntax: none gui.line(number x1, number y1, number x2, number y2[, number
5191 \begin_layout Standard
5196 \begin_layout Itemize
5197 x1: X-coordinate of one end.
5200 \begin_layout Itemize
5201 y1: Y-coordinate of one end.
5204 \begin_layout Itemize
5205 x2: X-coordinate of the other end.
5208 \begin_layout Itemize
5209 y2: Y-coordinate of the other end.
5212 \begin_layout Itemize
5213 color: Color of the line (default is 0xFFFFFF (white)).
5216 \begin_layout Subsection
5217 gui.circle: Draw a (filled) circle
5220 \begin_layout Itemize
5221 Syntax: none gui.circle(number x, number y, number r[, number thick[, number
5222 border[, number fil]]])
5225 \begin_layout Standard
5230 \begin_layout Itemize
5231 x: X-coordinate of the center
5234 \begin_layout Itemize
5235 y: Y-coordinate of the center
5238 \begin_layout Itemize
5239 r: The radius of the circle
5242 \begin_layout Itemize
5243 thick: Border thickness
5246 \begin_layout Itemize
5247 border: Border color (default is 0xFFFFFF (white))
5250 \begin_layout Itemize
5251 fill: Fill color (default is -1 (transparent)).
5254 \begin_layout Subsection
5255 gui.repaint: Arrange a repaint
5258 \begin_layout Itemize
5259 Syntax: none gui.repaint()
5262 \begin_layout Standard
5263 Request on_repaint() to happen as soon as possible.
5266 \begin_layout Subsection
5267 gui.subframe_update: Enable/Disable subframe updates
5270 \begin_layout Itemize
5271 Syntax: none gui.subframe_update(boolean on)
5274 \begin_layout Standard
5275 Request subframe updates (calling on_paint() on subframes) to happen (<on>=true)
5276 or not happen (<on>=false).
5279 \begin_layout Subsection
5280 gui.screenshot: Write a screenshot
5283 \begin_layout Itemize
5284 Syntax: none gui.screenshot(string filename)
5287 \begin_layout Standard
5288 Write PNG screenshot of the current frame (no drawings) to specified file
5292 \begin_layout Subsection
5293 gui.screenshot_bitmap: Write a screenshot to bitmap
5296 \begin_layout Itemize
5297 Syntax: DBITMAP gui.screenshot_bitmap()
5300 \begin_layout Standard
5301 Write PNG screenshot of the current frame (no drawings) to dbitmap and return
5305 \begin_layout Subsection
5306 gui.color: Compose a color.
5309 \begin_layout Itemize
5310 Syntax: number gui.color(number r, number g, number b[, number a])
5313 \begin_layout Itemize
5314 Syntax: number gui.color(string c)
5317 \begin_layout Standard
5318 Returns color (in notation Lua scripts use) corresponding to color (<r>,<g>,<b>)
5319 , each component in scale 0-255.
5320 If <a> is specified, that is alpha (0 is fully transparent, 256(sic) is
5322 The default alpha is 256.
5325 \begin_layout Standard
5326 The form taking a string returns color corresponding color name.
5329 \begin_layout Subsection
5330 gui.status: Set status variable
5333 \begin_layout Itemize
5334 Syntax: none gui.status(string name, string value)
5337 \begin_layout Standard
5339 \begin_inset Quotes eld
5343 \begin_inset Quotes erd
5346 to <value> in status area.
5349 \begin_layout Subsection
5350 gui.rainbow: Rainbow color calculation
5353 \begin_layout Itemize
5354 Syntax: number gui.rainbow(number step, number steps[, number color])
5357 \begin_layout Standard
5358 Perform hue rotation of color <color> (default bright red), by <step> steps.
5359 The number of steps per full rotation is given by absolute value of <steps>.
5362 \begin_layout Standard
5363 If <step> is negative, the rotation will be counterclockwise.
5366 \begin_layout Subsection
5367 gui.kill_frame: Kill video frame and associated sound
5370 \begin_layout Itemize
5371 Syntax: none gui.kill_frame()
5374 \begin_layout Standard
5375 Kills the currently dumped video frame + the associated sound.
5376 Only valid in on_video callback.
5379 \begin_layout Subsection
5380 gui.set_video_scale: Set video frame scale
5383 \begin_layout Itemize
5384 Syntax: none gui.set_video_scale(number h, number v)
5387 \begin_layout Standard
5388 Sets the scale factors of current frame to <h>x<v>.
5389 Only valid in on_video callback.
5392 \begin_layout Subsection
5393 gui.arrow: Draw an arrow
5396 \begin_layout Itemize
5397 Syntax: none gui.arrow(number x, number y, number length, number hwidth,
5398 number direction[, bool fill[, number color[, number twidth[, number hthick]]]]
5402 \begin_layout Standard
5403 Draws an arrow using color <color>.
5404 The tip of arrow is at (<x>, <y>).
5408 \begin_layout Enumerate
5409 <length>: The length of arrow tail.
5412 \begin_layout Enumerate
5413 <hwidth>: The width of arrow head.
5417 \begin_layout Enumerate
5418 <direction>: Direction of arrow.
5419 0 is to right, +1 rotates 45 degrees counterclockwise.
5422 \begin_layout Enumerate
5423 <fill>: If true, fill the arrow head.
5427 \begin_layout Enumerate
5428 <twidth>: Tail width.
5433 \begin_layout Enumerate
5434 <hthick>: Head thickness (only used if <fill> is false).
5435 Default is <twidth>.
5438 \begin_layout Subsection
5439 gui.tiled_bitmap: Class TILEMAP
5442 \begin_layout Standard
5446 \begin_layout Subsection
5447 gui.palette: Class PALETTE
5450 \begin_layout Standard
5454 \begin_layout Subsection
5455 gui.bitmap: Class BITMAP
5458 \begin_layout Standard
5462 \begin_layout Subsection
5463 gui.dbitmap: Class DBITMAP
5466 \begin_layout Standard
5470 \begin_layout Subsection
5471 gui.font: Class CUSTOMFONT
5474 \begin_layout Standard
5475 See class CUSTOMFONT.
5478 \begin_layout Subsection
5479 gui.renderctx: Class RENDERCTX
5482 \begin_layout Standard
5483 See class RENDERCTX.
5486 \begin_layout Subsection
5487 gui.image: Class IMAGELOADER
5490 \begin_layout Standard
5491 See class IMAGELOADER.
5494 \begin_layout Subsection
5495 gui.get_runmode: Get current emulator mode
5498 \begin_layout Itemize
5499 Syntax: string gui.get_runmode()
5502 \begin_layout Standard
5503 Gets the current emulator runmode.
5504 The possible ones are:
5507 \begin_layout Itemize
5508 quit: Emulator is quitting.
5511 \begin_layout Itemize
5512 normal: Emulator is running emulation
5515 \begin_layout Itemize
5516 load: Emulator is loading a movie/savestate
5519 \begin_layout Itemize
5520 advance_frame: Emulator is doing frame advance
5523 \begin_layout Itemize
5524 advance_subframe: Emulator is doing subframe advance
5527 \begin_layout Itemize
5528 skiplag: Emulator is skipping lag frames
5531 \begin_layout Itemize
5532 skiplag_pending: Emulator will start skipping lag frames next frame
5535 \begin_layout Itemize
5536 pause: Emulator is paused
5539 \begin_layout Itemize
5540 pause_break: Emulator is paused at breakpoint
5543 \begin_layout Itemize
5544 corrupt: Emulator can't run because corrupt emulation state
5547 \begin_layout Itemize
5548 unknown: Unknown state (should not happen).
5551 \begin_layout Standard
5552 \begin_inset Newpage pagebreak
5558 \begin_layout Section
5562 \begin_layout Standard
5564 Functions manipulating input are only available in on_input callback.
5567 \begin_layout Subsection
5568 input.get: Read controller button/axis (deprecated)
5571 \begin_layout Itemize
5572 Syntax: number input.get(number controller, number index)
5575 \begin_layout Standard
5576 Read the specified index <index> (zero-based) from specified controller
5577 <controller> (zero-based).
5581 \begin_layout Subsection
5582 input.set: Write controller button/axis (deprecated)
5585 \begin_layout Itemize
5586 Syntax: none input.set(number controller, number index, number value)
5589 \begin_layout Standard
5590 Write the specified index <index> (zero-based) from specified controller
5591 <controller> (zero-based), storing value <value>.
5594 \begin_layout Subsection
5595 input.get2: Read controller button/axis
5598 \begin_layout Itemize
5599 Syntax: number input.get2(number port, number controller, number index)
5602 \begin_layout Standard
5603 Read the specified input tuple.
5604 Port 0 is system port.
5607 \begin_layout Subsection
5608 input.set2: Write controller button/axis
5611 \begin_layout Itemize
5612 Syntax: input.set2(number port, number controller, number index, number value)
5615 \begin_layout Standard
5616 Write the specified input tuple.
5617 Port 0 is system port.
5620 \begin_layout Subsection
5621 input.lcid_to_pcid2: Look up logical controller
5624 \begin_layout Itemize
5625 Syntax: (number, number) input.lcid_to_pcid2(number lcid)
5628 \begin_layout Standard
5629 Look up physical pcid pair (port, controller) corresponding to specified
5630 logical controller (1-based).
5631 Returns nothing if controller does not exist.
5634 \begin_layout Subsection
5635 input.port_type: Look up port type
5638 \begin_layout Itemize
5639 Syntax: string input.port_type(number port)
5642 \begin_layout Standard
5643 Return type of specified port.
5646 \begin_layout Subsection
5647 input.controller_info: Get information about controller
5650 \begin_layout Itemize
5651 Syntax: table input.controller_info(number port, number controller)
5654 \begin_layout Standard
5655 Get controller info for specified controller.
5656 If controller does not exist, returns nil.
5657 Otherwise returns a table with following fields:
5660 \begin_layout Itemize
5661 type (string): Type of the controller.
5664 \begin_layout Itemize
5665 class (string): Class of the controller.
5668 \begin_layout Itemize
5669 classnum (number): Number of the controller within its class (1-based)
5672 \begin_layout Itemize
5673 lcid (number): Logical controller number of the controller.
5676 \begin_layout Itemize
5677 button_count (number): Number of buttons on controller
5680 \begin_layout Itemize
5681 buttons (array): Array of following info about each button:
5685 \begin_layout Itemize
5686 type (string): Type of button.
5688 \begin_inset Quotes eld
5692 \begin_inset Quotes erd
5696 \begin_inset Quotes eld
5700 \begin_inset Quotes erd
5704 \begin_inset Quotes eld
5708 \begin_inset Quotes erd
5712 \begin_inset Quotes eld
5716 \begin_inset Quotes erd
5722 \begin_layout Itemize
5723 name (string): Name of button.
5726 \begin_layout Itemize
5727 symbol (string): Symbol of button.
5728 Only present for type
5729 \begin_inset Quotes eld
5733 \begin_inset Quotes erd
5739 \begin_layout Itemize
5740 hidden (boolean): True if hidden button.
5745 \begin_layout Subsection
5746 input.veto_button: Veto a button press
5749 \begin_layout Itemize
5750 Syntax: none input.veto_button()
5753 \begin_layout Standard
5754 Signals that the button event should be vetoed.
5755 Only valid in on_button callback.
5758 \begin_layout Subsection
5759 input.geta: Get all buttons for controller (deprecated)
5762 \begin_layout Itemize
5763 Syntax: (number, number...) input.geta(number controller)
5766 \begin_layout Standard
5767 Get input state for entiere controller.
5768 Returns n return values.
5771 \begin_layout Itemize
5772 1st return value: Bitmask: bit i is set if i:th index is nonzero
5775 \begin_layout Itemize
5776 2nd- return value: value of i:th index.
5779 \begin_layout Subsection
5780 input.seta: Set all buttons for controller (deprecated)
5783 \begin_layout Itemize
5784 Syntax: none input.seta(number controller, number bitmask, number args...)
5787 \begin_layout Standard
5788 Set state for entiere controller.
5789 args is up to N values for indices (overriding values in bitmask if specified).
5792 \begin_layout Subsection
5793 input.controllertype: Get controller type (deprecated)
5796 \begin_layout Itemize
5797 syntax: string input.controllertype(number controller)
5800 \begin_layout Standard
5801 Get the type of controller as string.
5804 \begin_layout Subsection
5805 input.reset: Execute (delayed) reset
5808 \begin_layout Itemize
5809 Syntax: none input.reset([number cycles])
5812 \begin_layout Standard
5814 If <cycles> is greater than zero, do delayed reset.
5815 0 (or no value) causes immediate reset.
5818 \begin_layout Itemize
5819 Note: Only available with subframe flag false.
5822 \begin_layout Subsection
5823 input.raw: Return raw input data
5826 \begin_layout Itemize
5827 Syntax: table input.raw()
5830 \begin_layout Standard
5831 Returns table of tables of all available keys and axes.
5832 The first table is indexed by key name (platform-dependent!), and the inner
5833 table has the following fields:
5836 \begin_layout Itemize
5837 value: Last reported value for control
5841 \begin_layout Itemize
5842 For keys: 1 for pressed, 0 for released.
5845 \begin_layout Itemize
5846 For axes: -32767...32767.
5849 \begin_layout Itemize
5850 For presure-sensitive buttons: 0...32767.
5853 \begin_layout Itemize
5854 For hats: Bitmask: 1=>Up, 2=>Right, 4=>Down, 8=>Left.
5857 \begin_layout Itemize
5858 For mouse: Coordinates relative to game area.
5862 \begin_layout Itemize
5863 ktype: Type of key (disabled, key, mouse, axis, hat, pressure).
5866 \begin_layout Subsection
5867 input.keyhook: Hook a key
5870 \begin_layout Itemize
5871 Syntax: none input.keyhook(string key, boolean state)
5874 \begin_layout Standard
5875 Requests that keyhook events to be sent for key <key> (<state>=true) or
5876 not sent (<state>=false).
5879 \begin_layout Subsection
5880 input.joyget: Get controls for controller
5883 \begin_layout Itemize
5884 Syntax: table input.joyget(number logical)
5887 \begin_layout Standard
5888 Returns table for current controls for specified logical controller <logical>.
5889 The names of fields vary by controller type.
5892 \begin_layout Itemize
5893 The buttons have the same name as those are referred to in other contexts
5897 \begin_layout Itemize
5898 The analog axes are usually
5899 \begin_inset Quotes eld
5903 \begin_inset Quotes erd
5907 \begin_inset Quotes eld
5911 \begin_inset Quotes erd
5917 \begin_layout Itemize
5918 Each field is numeric or boolean depending on axis/button.
5921 \begin_layout Subsection
5922 input.joyset: Set controls for controller
5925 \begin_layout Itemize
5926 Syntax: none input.joyset(number controller, table controls)
5929 \begin_layout Standard
5930 Set the the state of specified controller to values specified in specified
5934 \begin_layout Itemize
5935 Each field can be boolean or number.
5938 \begin_layout Itemize
5939 Also, buttons allow strings, which cause value to be inverted.
5942 \begin_layout Subsection
5943 input.lcid_to_pcid: Look up logical controller (deprecated)
5946 \begin_layout Itemize
5947 Syntax: (number, number, number) input.lcid_to_pcid(number lcid)
5950 \begin_layout Standard
5951 Returns the legacy pcid for controller (or false if there isn't one), followed
5953 Returns nothing if controller does not exist.
5956 \begin_layout Standard
5957 \begin_inset Newpage pagebreak
5963 \begin_layout Section
5967 \begin_layout Standard
5968 Various keybinding-related functions
5971 \begin_layout Subsection
5972 keyboard.bind: Bind a key
5975 \begin_layout Itemize
5976 Syntax: none keyboard.bind(string mod, string mask, string key, string cmd)
5979 \begin_layout Standard
5980 Bind specified key with specified modifers to specified command.
5983 \begin_layout Subsection
5984 keyboard.unbind: Unbind a key
5987 \begin_layout Itemize
5988 Syntax: none keyboard.unbind(string mod, string mask, string key)
5991 \begin_layout Standard
5992 Unbind specified key with specified modifers.
5995 \begin_layout Subsection
5996 keyboard.alias: Set alias expansion
5999 \begin_layout Itemize
6000 Syntax: none keyboard.alias(string alias, string expansion)
6003 \begin_layout Standard
6004 Set expansion of given command.
6007 \begin_layout Standard
6008 \begin_inset Newpage pagebreak
6014 \begin_layout Section
6018 \begin_layout Standard
6022 \begin_layout Subsection
6023 subtitle.byindex: Look up start and length of subtitle by index
6026 \begin_layout Itemize
6027 Syntax: (number, number) subtitle.byindex(number i)
6030 \begin_layout Standard
6031 Read the frame and length of ith subtitle.
6032 Returns nothing if not present.
6035 \begin_layout Subsection
6036 subtitle.set: Write a subtitle
6039 \begin_layout Itemize
6040 Syntax: none subtitle.set(number f, number l, string txt)
6043 \begin_layout Standard
6044 Set the text of subtitle.
6047 \begin_layout Subsection
6048 subtitle.get: Read a subtitle
6051 \begin_layout Itemize
6052 Syntax: string subtitle.get(number f, number l)
6055 \begin_layout Standard
6056 Get the text of subtitle.
6059 \begin_layout Subsection
6060 subtitle.delete: Delete a subtitle
6063 \begin_layout Itemize
6064 Syntax: none subtitle.delete(number f, number l)
6067 \begin_layout Standard
6068 Delete specified subtitle.
6071 \begin_layout Standard
6072 \begin_inset Newpage pagebreak
6078 \begin_layout Section
6082 \begin_layout Standard
6083 Host memory handling (extra memory saved to savestates).
6084 Host memory starts empty.
6087 \begin_layout Itemize
6088 Reads out of range return false.
6091 \begin_layout Itemize
6092 Writes out of range extend the memory.
6095 \begin_layout Subsection
6096 hostmemory.read: Read byte from host memory
6099 \begin_layout Itemize
6100 Syntax: number hostmemory.read(number address)
6103 \begin_layout Standard
6104 Reads byte from hostmemory slot address <address>.
6107 \begin_layout Subsection
6108 hostmemory.write: Write byte to host memory
6111 \begin_layout Itemize
6112 Syntax: none hostmemory.write(number address, number value)
6115 \begin_layout Standard
6116 Writes hostmemory slot with value <value> 0-255.
6119 \begin_layout Subsection
6120 hostmemory.read{,s}{byte,{,h,d,q}word}: Read from host memory
6123 \begin_layout Itemize
6124 Syntax: number hostmemory.readbyte(number address)
6127 \begin_layout Itemize
6128 Syntax: number hostmemory.readsbyte(number address)
6131 \begin_layout Itemize
6132 Syntax: number hostmemory.readword(number address)
6135 \begin_layout Itemize
6136 Syntax: number hostmemory.readsword(number address)
6139 \begin_layout Itemize
6140 Syntax: number hostmemory.readhword(number address)
6143 \begin_layout Itemize
6144 Syntax: number hostmemory.readshword(number address)
6147 \begin_layout Itemize
6148 Syntax: number hostmemory.readdword(number address)
6151 \begin_layout Itemize
6152 Syntax: number hostmemory.readsdword(number address)
6155 \begin_layout Itemize
6156 Syntax: number hostmemory.readqword(number address)
6159 \begin_layout Itemize
6160 Syntax: number hostmemory.readsqword(number address)
6163 \begin_layout Standard
6164 Read elements (big-endian) from given address <address>.
6167 \begin_layout Itemize
6171 \begin_layout Itemize
6175 \begin_layout Itemize
6179 \begin_layout Itemize
6183 \begin_layout Itemize
6184 qword is 8 elements.
6187 \begin_layout Itemize
6188 The 's' variants do signed read.
6191 \begin_layout Subsection
6192 hostmemory.read{float,double}: Read from host memory
6195 \begin_layout Itemize
6196 syntax: number hostmemory.readfloat(number address)
6199 \begin_layout Itemize
6200 Syntax: number hostmemory.readdouble(number address)
6203 \begin_layout Standard
6204 Read elements (big-endian) floating-pont from given address <address>.
6207 \begin_layout Subsection
6208 hostmemory.write{,s}{byte,{,h,d,q}word}: Write to host memory
6211 \begin_layout Itemize
6212 Syntax: number hostmemory.writebyte(number address, number value)
6215 \begin_layout Itemize
6216 Syntax: number hostmemory.writesbyte(number address, number value)
6219 \begin_layout Itemize
6220 Syntax: number hostmemory.writeword(number address, number value)
6223 \begin_layout Itemize
6224 Syntax: number hostmemory.writesword(number address, number value)
6227 \begin_layout Itemize
6228 Syntax: number hostmemory.writehword(number address, number value)
6231 \begin_layout Itemize
6232 Syntax: number hostmemory.writeshword(number address, number value)
6235 \begin_layout Itemize
6236 Syntax: number hostmemory.writedword(number address, number value)
6239 \begin_layout Itemize
6240 Syntax: number hostmemory.writesdword(number address, number value)
6243 \begin_layout Itemize
6244 Syntax: number hostmemory.writeqword(number address, number value)
6247 \begin_layout Itemize
6248 Syntax: number hostmemory.writesqword(number address, number value)
6251 \begin_layout Standard
6252 Write value <value> to elements (little-endian) starting from given address
6256 \begin_layout Itemize
6260 \begin_layout Itemize
6264 \begin_layout Itemize
6268 \begin_layout Itemize
6272 \begin_layout Itemize
6273 qword is 8 elements.
6276 \begin_layout Itemize
6277 The 's' variants do signed write.
6280 \begin_layout Subsection
6281 hostmemory.write{float,double}: Write to host memory
6284 \begin_layout Itemize
6285 syntax: none hostmemory.readfloat(number address, number value)
6288 \begin_layout Itemize
6289 Syntax: none hostmemory.readdouble(number address, number value)
6292 \begin_layout Standard
6293 Write elements (big-endian) floating-pont to given address <address>, storing
6297 \begin_layout Standard
6298 \begin_inset Newpage pagebreak
6304 \begin_layout Section
6308 \begin_layout Standard
6312 \begin_layout Subsection
6313 movie.currentframe: Get current frame number
6316 \begin_layout Itemize
6317 Syntax: number movie.currentframe()
6320 \begin_layout Standard
6321 Return number of current frame.
6324 \begin_layout Subsection
6325 movie.framecount: Get move frame count
6328 \begin_layout Itemize
6329 Syntax: number movie.framecount()
6332 \begin_layout Standard
6333 Return number of frames in movie.
6336 \begin_layout Subsection
6337 movie.lagcount: Get current lag count
6340 \begin_layout Itemize
6341 Syntax: number movie.lagcount()
6344 \begin_layout Standard
6345 Return number of lag frames recorded so far.
6348 \begin_layout Subsection
6349 movie.readonly: Is in playback mode?
6352 \begin_layout Itemize
6353 Syntax: boolean movie.readonly()
6356 \begin_layout Standard
6357 Return true if in playback mode, false if in recording.
6360 \begin_layout Subsection
6361 movie.rerecords: Movie rerecord count
6364 \begin_layout Itemize
6365 Syntax: number movie.rerecords()
6368 \begin_layout Standard
6369 Returns the current value of rerecord count.
6372 \begin_layout Subsection
6373 movie.set_readwrite: Set recording mode.
6376 \begin_layout Itemize
6377 Syntax: none movie.set_readwrite()
6380 \begin_layout Standard
6381 Set recording mode (does not cause on_readwrite callback).
6384 \begin_layout Subsection
6385 movie.frame_subframes: Count subframes in frame
6388 \begin_layout Itemize
6389 Syntax: number movie.frame_subframes(number frame)
6392 \begin_layout Standard
6393 Count number of subframes in specified frame <frame> (frame numbers are
6394 1-based) and return that.
6397 \begin_layout Subsection
6398 movie.read_subframes: Read subframe data (deprecated)
6401 \begin_layout Itemize
6402 Syntax: table movie.read_subframes(number frame, number subframe)
6405 \begin_layout Standard
6406 Read specifed subframe in specified frame and return data as array.
6409 \begin_layout Subsection
6410 movie.read_rtc: Read current RTC time
6413 \begin_layout Itemize
6414 Syntax: (number, number) movie.read_rtc()
6417 \begin_layout Standard
6418 Returns the current value of the RTC as a pair (second, subsecond).
6421 \begin_layout Subsection
6422 movie.unsafe_rewind: Fast movie rewind to saved state
6425 \begin_layout Itemize
6426 Syntax: none movie.unsafe_rewind([UNSAFEREWIND state])
6429 \begin_layout Standard
6430 Start setting point for unsafe rewind or jump to point of unsafe rewind.
6433 \begin_layout Itemize
6434 If called without argument, causes emulator to start process of setting
6435 unsafe rewind point.
6436 When this has finished, callback on_set_rewind occurs, passing the rewind
6437 state to lua script.
6440 \begin_layout Itemize
6441 If called with argument, causes emulator rewind to passed rewind point as
6443 recording mode is implicitly activated.
6446 \begin_layout Standard
6447 The following warnings apply to unsafe rewinding:
6450 \begin_layout Itemize
6451 There are no safety checks against misuse (that's what
6452 \begin_inset Quotes eld
6456 \begin_inset Quotes erd
6462 \begin_layout Itemize
6463 Only call rewind from timeline rewind point was set from.
6466 \begin_layout Itemize
6467 Only call rewind from after the rewind point was set.
6470 \begin_layout Subsection
6471 movie.to_rewind: Load savestate as rewind point
6474 \begin_layout Itemize
6475 Syntax: UNSAFEREWIND movie.to_rewind(string filename)
6478 \begin_layout Standard
6479 Load specified savestate file <filename> as rewind point and return UNSAFEREWIND
6480 corresponding to it.
6483 \begin_layout Itemize
6484 Note: This operation does not take emulated time.
6487 \begin_layout Subsection
6488 movie.copy_movie/INPUTMOVIE::copy_movie: Copy movie to movie object
6491 \begin_layout Itemize
6492 Syntax: INPUTMOVIE movie.copy_movie([INPUTMOVIE/string movie])
6495 \begin_layout Itemize
6496 Syntax: INPUTMOVIE INPUTMOVIE::copy_movie()
6499 \begin_layout Standard
6500 Copies specified movie or branch <movie>/current object (if none or nil,
6501 the active movie) as new movie object.
6504 \begin_layout Subsection
6505 movie.get_frame/INPUTMOVIE::get_frame: Read specified frame in movie.
6508 \begin_layout Itemize
6509 Syntax: INPUTFRAME movie.get_frame([INPUTMOVIE/string movie,] number frame)
6512 \begin_layout Itemize
6513 Syntax: INPUTFRAME INPUTMOVIE::get_frame(number frame);
6516 \begin_layout Standard
6517 Get INPUTFRAME object corresponding to specified frame in specified movie
6521 \begin_layout Subsection
6522 movie.set_frame/INPUTMOVIE::set_frame: Write speicifed frame in movie.
6525 \begin_layout Itemize
6526 Syntax: none movie.set_frame([INPUTMOVIE/string movie,] number frame, INPUTFRAME
6530 \begin_layout Itemize
6531 Syntax: none INPUTMOVIE::set_frame(number frame, INPUTFRAME data)
6534 \begin_layout Standard
6535 Set data in specified frame.
6538 \begin_layout Itemize
6539 Note: Past can't be edited in active movie.
6542 \begin_layout Subsection
6543 movie.get_size/INPUTMOVIE::get_size: Get size of movie
6546 \begin_layout Itemize
6547 Syntax: integer movie.get_size([INPUTMOVIE/string movie])
6550 \begin_layout Itemize
6551 Syntax: integer INPUTMOVIE::get_size()
6554 \begin_layout Standard
6555 Return number of subframes in specified movie or branch.
6558 \begin_layout Subsection
6559 movie.count_frames/INPUTMOVIE::count_frames: Count frames in movie
6562 \begin_layout Itemize
6563 Syntax: number movie.count_frames([INPUTMOVIE/string movie])
6566 \begin_layout Itemize
6567 Syntax: number INPUTMOVIE::count_frames()
6570 \begin_layout Standard
6571 Return number of frames in movie.
6574 \begin_layout Subsection
6575 movie.find_frame/INPUTMOVIE::find_frame: Find subframe corresponding to frame
6578 \begin_layout Itemize
6579 Syntax: number movie.find_frame([INPUTMOVIE/string movie], number frame)
6582 \begin_layout Itemize
6583 Syntax: number INPUTMOVIE::find_frame(number frame)
6586 \begin_layout Standard
6587 Returns starting subframe of given frame (frame numbers are 1-based).
6588 Returns -1 if frame number is bad.
6591 \begin_layout Subsection
6592 movie.blank_frame/INPUTMOVIE::blank_frame: Return a blank frame
6595 \begin_layout Itemize
6596 Syntax: INPUTFRAME movie.blank_frame([INPUTMOVIE/string movie])
6599 \begin_layout Itemize
6600 Syntax: INPUTFRAME INPUTMOVIE::blank_frame()
6603 \begin_layout Standard
6604 Return blank INPUTFRAME with frame type from specified movie.
6607 \begin_layout Subsection
6608 movie.append_frames/INPUTMOVIE::append_frames: Append blank frames
6611 \begin_layout Itemize
6612 Syntax: none movie.append_frames([INPUTMOVIE/string movie,] number frames)
6615 \begin_layout Itemize
6616 Syntax: none INPUTMOVIE::append_frames(number frames)
6619 \begin_layout Standard
6620 Append specified number <frames> of frames.
6623 \begin_layout Subsection
6624 movie.append_frame/INPUTMOVIE::append_frame: Append a frame
6627 \begin_layout Itemize
6628 Syntax: none movie.append_frame([INPUTMOVIE/string movie,] INPUTFRAME frame)
6631 \begin_layout Itemize
6632 Syntax: none INPUTMOVIE::append_frame(INPUTFRAME frame)
6635 \begin_layout Standard
6636 Append specified frame <frame>.
6637 Past of current movie can't be edited.
6640 \begin_layout Subsection
6641 movie.truncate/INPUTMOVIE::truncate: Truncate a movie.
6644 \begin_layout Itemize
6645 Syntax: none movie.truncate([INPUTMOVIE/string movie,] number frames)
6648 \begin_layout Itemize
6649 Syntax: none INPUTMOVIE::truncate(number frames)
6652 \begin_layout Standard
6653 Truncate the specified movie to specified number of frames.
6656 \begin_layout Subsection
6657 movie.edit/INPUTMOVIE::edit: Edit a movie
6660 \begin_layout Itemize
6661 Syntax: none movie.edit([INPUTMOVIE movie,] number frame, number port, number
6662 controller, number control, number/bool value)
6665 \begin_layout Itemize
6666 Syntax: none movie.edit(string branch, number frame, number port, number
6667 controller, number control, number/bool value)
6670 \begin_layout Itemize
6671 Syntax: none INPUTMOVIE::edit(number frame, number port, number controller,
6672 number control, number/bool value)
6675 \begin_layout Standard
6676 Change specified control in specified frame in specified movie.
6677 Past can't be edited in active movie.
6680 \begin_layout Subsection
6681 movie.copy_frames2: Copy frames between movies
6684 \begin_layout Itemize
6685 Syntax: none movie.copy_frames2([INPUTMOVIE/string dstmov,] number dst, [INPUTMOV
6686 IE/string srcmov,] number src, number count)
6689 \begin_layout Standard
6690 Copy specified number of frames between two movies.
6691 The copy proceeeds in forward direction.
6694 \begin_layout Subsection
6695 movie.copy_frames/INPUTMOVIE::copy_frames: Copy frames in movie
6698 \begin_layout Itemize
6699 Syntax: none movie.copy_frames([INPUTMOVIE/string mov,] number dst, number
6700 src, number count, bool backwards)
6703 \begin_layout Itemize
6704 Syntax: none INPUTMOVIE::copy_frames(number dst, number src, number count,
6708 \begin_layout Standard
6709 Copy specified number of frames from one point in movie to another.
6710 If backwards is true, the copy will be done backwards.
6713 \begin_layout Subsection
6714 movie.serialize/INPUTMOVIE::serialize: Serialize movie
6717 \begin_layout Itemize
6718 Syntax: none movie.serialize([INPUTMOVIE movie/string,] string filename,
6722 \begin_layout Itemize
6723 Syntax: none INPUTMOIVE::serialize(string filename, bool binary)
6726 \begin_layout Standard
6727 Serialize given movie into file.
6728 If binary is true, binary format (more compact and much faster) is used.
6731 \begin_layout Subsection
6732 movie.unserialize: Unserialize movie
6735 \begin_layout Itemize
6736 Syntax: INPUTMOVIE movie.unserialize(INPUTFRAME template, string filename,
6740 \begin_layout Standard
6741 Unserialize movie from file.
6742 The given frame is used as template to decide the frame type.
6743 If binary is true, binary format is decoded (much faster).
6746 \begin_layout Subsection
6747 movie.current_first_subframe: Return first subframe in current frame
6750 \begin_layout Itemize
6751 Syntax: number movie.current_first_subframe()
6754 \begin_layout Standard
6755 Returns first subframe in current frame.
6758 \begin_layout Subsection
6759 movie.pollcounter: Return poll counter for speified control
6762 \begin_layout Itemize
6763 Syntax: number movie.pollcounter(number port, number controller, number control)
6766 \begin_layout Standard
6767 Returns number of times the specified control has been polled this frame.
6770 \begin_layout Subsection
6771 movie.current_branch: Return current branch
6774 \begin_layout Itemize
6775 Syntax: string movie.current_branch()
6778 \begin_layout Standard
6779 Returns the name of the current branch.
6782 \begin_layout Subsection
6783 movie.get_branches: Return names of all branches
6786 \begin_layout Itemize
6788 movie.get_branches()
6791 \begin_layout Standard
6792 Returns the name of all branches.
6795 \begin_layout Subsection
6796 INPUTFRAME::get_button: Get button
6799 \begin_layout Itemize
6800 Syntax: boolean INPUTFRAME::get_button(number port, number controller, number
6804 \begin_layout Standard
6805 Returns state of given button as boolean.
6808 \begin_layout Subsection
6809 INPUTFRAME::get_axis: Get axis
6812 \begin_layout Itemize
6813 Syntax: number INPUTFRAME::get_axis(number port, number controller, number
6817 \begin_layout Standard
6818 Returns state of given axis as number.
6821 \begin_layout Subsection
6822 INPUTFRAME::set_button/INPUTFRAME::set_axis: Set button or axis
6825 \begin_layout Itemize
6826 Syntax: none INPUTFRAME::set_button(number port, number controller, number
6827 control, number/bool value)
6830 \begin_layout Itemize
6831 Syntax: none INPUTFRAME::set_axis(number port, number controller, number
6835 \begin_layout Standard
6836 Set the given button/axis to given value.
6839 \begin_layout Subsection
6840 INPUTFRAME::serialize: Serialize a frame
6843 \begin_layout Itemize
6844 Syntax: string INPUTFRAME::serialize()
6847 \begin_layout Standard
6848 Return string representation of frame.
6851 \begin_layout Subsection
6852 INPUTFRAME::unserialize: Unserialize a frame
6855 \begin_layout Itemize
6856 Syntax: none INPUTFRAME::unserialize(string data)
6859 \begin_layout Standard
6860 Set current frame from given data.
6863 \begin_layout Subsection
6864 INPUTFRAME::get_stride: Get movie stride
6867 \begin_layout Itemize
6868 Syntax: number INPUTFRAME::get_stride()
6871 \begin_layout Standard
6872 Return number of bytes needed to store the input frame.
6873 Mainly useful for some debugging.
6876 \begin_layout Standard
6877 \begin_inset Newpage pagebreak
6883 \begin_layout Section
6887 \begin_layout Standard
6888 Routines for settings manipulation
6891 \begin_layout Subsection
6892 settings.get: Get value of setting
6895 \begin_layout Itemize
6896 Syntax: string settings.get(string name)
6899 \begin_layout Standard
6900 Get value of setting <name>.
6901 If setting value can't be obtained, returns (nil, error message).
6904 \begin_layout Subsection
6905 settings.set: Set value of setting
6908 \begin_layout Itemize
6909 Syntax: none settings.set(string name, string value)
6912 \begin_layout Standard
6913 Set value <value> of setting <name>.
6914 If setting can't be set, returns (nil, error message).
6917 \begin_layout Subsection
6918 settings.get_all: Get values of all settings
6921 \begin_layout Itemize
6922 Syntax: table settings.get_all()
6925 \begin_layout Standard
6926 Return a table with all setting names as keys and all current values as
6930 \begin_layout Subsection
6931 settings.get_speed: Get current speed
6934 \begin_layout Itemize
6935 Syntax: number/string settings.get_speed()
6938 \begin_layout Standard
6939 Return the current speed multiplier (1 is normal), or
6940 \begin_inset Quotes eld
6944 \begin_inset Quotes erd
6947 if speed is set to turbo (this does not react to turbo toggle).
6950 \begin_layout Subsection
6951 settings.set_speed: Set current speed
6954 \begin_layout Itemize
6955 Syntax: settings.get_speed(number spd)
6958 \begin_layout Itemize
6959 Syntax: settings.get_speed(string special)
6962 \begin_layout Standard
6963 Set the current speed multiplier (1 is normal).
6964 The speed may be positive multiplier or
6965 \begin_inset Quotes eld
6969 \begin_inset Quotes erd
6975 \begin_layout Standard
6976 \begin_inset Newpage pagebreak
6982 \begin_layout Section
6986 \begin_layout Standard
6987 Contains various functions for managing memory
6990 \begin_layout Subsection
6991 memory.vma_count: Count number of memory areas.
6994 \begin_layout Itemize
6995 Syntax: number memory.vma_count()
6998 \begin_layout Standard
6999 Returns the number of memory areas
7002 \begin_layout Subsection
7003 memory.read_vma: Lookup memory area info by index
7006 \begin_layout Itemize
7007 Syntax: table memory.read_vma(number index)
7010 \begin_layout Standard
7011 Reads the specified memory area (indices start from zero).
7012 Trying to read invalid memory area gives nil.
7013 The return value is table with the following fields:
7016 \begin_layout Itemize
7017 region_name (string): The readable name of the memory area
7020 \begin_layout Itemize
7021 baseaddr (number): Base address of the memory area
7024 \begin_layout Itemize
7025 lastaddr (number): Last address in the memory area.
7028 \begin_layout Itemize
7029 size (number): The size of memory area in bytes.
7032 \begin_layout Itemize
7033 readonly (boolean): True of the memory area corresponds to ROM.
7036 \begin_layout Itemize
7037 iospace (boolean): True if the memory area is I/O space.
7040 \begin_layout Itemize
7041 native_endian (boolean): True if the memory area has native endian as opposed
7045 \begin_layout Subsection
7046 memory.find_vma: Find memory area info by address
7049 \begin_layout Itemize
7050 Syntax: table memory.find_vma(number address)
7053 \begin_layout Standard
7054 Finds the memory area containing specified address.
7055 Returns table in the same format as read_vma or nil if not found.
7058 \begin_layout Subsection
7059 memory.read{,s}{byte,{,h,d,q}word}: Read memory
7062 \begin_layout Itemize
7063 Syntax: none memory.readbyte({string marea, number address|ADDRESS addrobj})
7066 \begin_layout Itemize
7067 Syntax: none memory.readword({string marea, number address|ADDRESS addrobj})
7070 \begin_layout Itemize
7071 Syntax: none memory.readhword({string marea, number address|ADDRESS addrobj})
7074 \begin_layout Itemize
7075 Syntax: none memory.readdword({string marea, number address|ADDRESS addrobj})
7078 \begin_layout Itemize
7079 Syntax: none memory.readqword({string marea, number address|ADDRESS addrobj})
7082 \begin_layout Itemize
7083 Syntax: none memory.readsbyte({string marea, number address|ADDRESS addrobj})
7086 \begin_layout Itemize
7087 Syntax: none memory.readsword({string marea, number address|ADDRESS addrobj})
7090 \begin_layout Itemize
7091 Syntax: none memory.readshword({string marea, number address|ADDRESS addrobj})
7094 \begin_layout Itemize
7095 Syntax: none memory.readsdword({string marea, number address|ADDRESS addrobj})
7098 \begin_layout Itemize
7099 Syntax: none memory.readsqword({string marea, number address|ADDRESS addrobj})
7102 \begin_layout Standard
7103 Reads the specified address <address> (if 's' variant is used, do undergo
7107 \begin_layout Subsection
7108 memory.{,s}read_sg: Scatter/Gather read memory
7111 \begin_layout Itemize
7112 Syntax: none memory.read_sg(string/boolean/number...)
7115 \begin_layout Itemize
7116 Syntax: none memory.sread_sg(string/boolean/number...)
7119 \begin_layout Standard
7120 Perform (2s complement signed if using memory.sread_sg) scatter/gather read
7122 Each argument can be string, boolean or number:
7125 \begin_layout Itemize
7126 String: Set memory area addresses are relative to (e.g.
7130 \begin_layout Itemize
7131 boolean: If true, increment relative address by 1, if false, decrement by
7133 The new address is read as next higher byte.
7136 \begin_layout Itemize
7137 integer: Set the relative address to specified value and read the address
7138 as next higher byte.
7141 \begin_layout Subsection
7142 memory.write_sg: Scatter/Gather write memory
7145 \begin_layout Itemize
7146 Syntax: none memory.write_sg(number value, string/boolean/number...)
7149 \begin_layout Standard
7150 Perform scatter/gather write of value <value> on memory.
7151 Each argument can be string, boolean or number:
7154 \begin_layout Itemize
7155 String: Set memory area addresses are relative to (e.g.
7159 \begin_layout Itemize
7160 boolean: If true, increment relative address by 1, if false, decrement by
7162 The new address is read as next higher byte.
7165 \begin_layout Itemize
7166 integer: Set the relative address to specified value and read the address
7167 as next higher byte.
7170 \begin_layout Subsection
7171 memory.read{float,double}: Read memory
7174 \begin_layout Itemize
7175 Syntax: none memory.readfloat({string marea, number address|ADDRESS addrobj})
7178 \begin_layout Itemize
7179 Syntax: none memory.readdouble({string marea, number address|ADDRESS addrobj})
7182 \begin_layout Standard
7183 Reads the specified address <address>
7186 \begin_layout Subsection
7187 memory.write{byte,{,h,d,q}word,float,double}: Write memory
7190 \begin_layout Itemize
7191 Syntax: none memory.writebyte({string marea, number address|ADDRESS addrobj},
7195 \begin_layout Itemize
7196 Syntax: none memory.writeword({string marea, number address|ADDRESS addrobj},
7200 \begin_layout Itemize
7201 Syntax: none memory.writehword({string marea, number address|ADDRESS addrobj},
7205 \begin_layout Itemize
7206 Syntax: none memory.writedword({string marea, number address|ADDRESS addrobj},
7210 \begin_layout Itemize
7211 Syntax: none memory.writeqword({string marea, number address|ADDRESS addrobj},
7215 \begin_layout Itemize
7216 Syntax: none memory.writefloat({string marea, number address|ADDRESS addrobj},
7220 \begin_layout Itemize
7221 Syntax: none memory.writedouble({string marea, number address|ADDRESS addrobj},
7225 \begin_layout Standard
7226 Writes the specified value <value> (negative integer values undergo 2's
7227 complement) to specified address <address>.
7230 \begin_layout Subsection
7231 memory.map{{,s}{byte,{,h,d,q}word},float,double}: Map an array
7234 \begin_layout Itemize
7235 Syntax: userdata memory.map<type>({string marea, number base|ADDRESS addrobj},
7239 \begin_layout Standard
7240 Returns a table mapping specified memory aperture for read/write.
7243 \begin_layout Itemize
7244 Type may be one of: byte, sbyte, word, sword, hword, shword, dword, sdword,
7245 qword, sqword, float or double.
7248 \begin_layout Subsection
7249 memory.hash_region: Hash region of memory
7252 \begin_layout Itemize
7253 Syntax: string memory.hash_region({string marea, number base|ADDRESS addrobj},
7257 \begin_layout Standard
7258 Hash <size> bytes starting from address <base> (relative to <marea>) and
7262 \begin_layout Subsection
7263 memory.hash_region2: Hash region of memory
7266 \begin_layout Itemize
7267 Syntax: string memory.hash_region2({string marea, number base|ADDRESS addrobj},
7268 number size[, number rows, number stride])
7271 \begin_layout Standard
7272 Hash <rows> blocks of <size> bytes starting from address <base> (relative
7274 The blocks are offset by <stride> from one another and return the SHA-256.
7277 \begin_layout Subsection
7278 memory.hash_region_skein: Hash region of memory
7281 \begin_layout Itemize
7282 Syntax: string memory.hash_region_skein({string marea, number base|ADDRESS
7283 addrobj}, number size[, number rows, number stride])
7286 \begin_layout Standard
7287 Same as memory.hash_region2, but uses Skein-512-256 (v1.3; one of the SHA-3
7288 finalists) as hash function.
7291 \begin_layout Subsection
7292 memory.store: Store region of memory
7295 \begin_layout Itemize
7296 Syntax: none memory.store({string marea, number addr|ADDRESS addrobj}, number
7297 daddr[, number rows, number stride]
7300 \begin_layout Standard
7301 Copy memory starting from <addr> in memory area <marea> (each row being
7302 of size <size>, there being <rows> rows, and rows being separated by <stride>
7303 in memory) into savestate-saved memory area, starting from <daadr> (all
7304 rows are written back to back).
7307 \begin_layout Subsection
7308 memory.storecmp: Compare and store region of memory
7311 \begin_layout Itemize
7312 Syntax: bool memory.storecmp({string marea, number addr|ADDRESS addrobj},
7313 number daddr[, number rows, number stride]
7316 \begin_layout Standard
7317 Like memory.store, but returns true if target of copy already held the value
7318 that would be copied before the copy happened.
7319 Otherwise returns false (if target and source differ before copy).
7322 \begin_layout Subsection
7323 memory.hash_state: Hash system state
7326 \begin_layout Itemize
7327 Syntax: string memory.hash_state()
7330 \begin_layout Standard
7331 Hash the current system state.
7332 Mainly useful for debugging savestates.
7335 \begin_layout Subsection
7336 memory.readregion: Read region of memory
7339 \begin_layout Itemize
7340 Syntax: table memory.readregion({string marea, number base|ADDRESS addrobj},
7344 \begin_layout Standard
7345 Read a region of memory.
7348 \begin_layout Itemize
7349 Warning: If the region crosses memory area boundary, the results are undefined.
7352 \begin_layout Subsection
7353 memory.writeregion: Write region of memory
7356 \begin_layout Itemize
7357 Syntax: none memory.writeregion({string marea, number base|ADDRESS addrobj},
7358 number size, table data)
7361 \begin_layout Standard
7362 Write a region of memory.
7365 \begin_layout Itemize
7366 Warning: If the region crosses memory area boundary, the results are undefined.
7369 \begin_layout Subsection
7370 memory.action: Run core action
7373 \begin_layout Itemize
7374 memory.action(string action, [<params>])
7377 \begin_layout Standard
7379 The different models expect parameters as:
7382 \begin_layout Itemize
7386 \begin_layout Itemize
7390 \begin_layout Itemize
7394 \begin_layout Itemize
7398 \begin_layout Itemize
7402 \begin_layout Subsection
7403 memory.action_flags: Get core action flags
7406 \begin_layout Itemize
7407 memory.action_flags(string action)
7410 \begin_layout Standard
7411 Get value of action flags for core action <action>.
7414 \begin_layout Itemize
7418 \begin_layout Itemize
7419 Bit 1: Selected (not all actions can be selected)?
7422 \begin_layout Subsection
7423 memory.get_lag_flag: Get lag flag
7426 \begin_layout Itemize
7427 Syntax: boolean memory.get_lag_flag()
7430 \begin_layout Standard
7431 Get the value of core lag flag.
7432 True if this frame has been lag so far, false if poll has been detected.
7435 \begin_layout Subsection
7436 memory.set_lag_flag: Set lag flag
7439 \begin_layout Itemize
7440 Syntax: none memory.set_lag_flag(boolean flag)
7443 \begin_layout Standard
7444 Set the value of core lag flag.
7445 This flag automatically gets cleared if poll is detected, but can be forcibly
7446 set or cleared if game so requires.
7449 \begin_layout Itemize
7450 Should only be used in on_frame_emulated callback.
7453 \begin_layout Itemize
7454 Setting or clearing this affects the emulator lag counter.
7457 \begin_layout Subsection
7458 memory.{,un}register{read,write,exec}: (Un)Register read / write / execute
7462 \begin_layout Itemize
7463 Syntax: function memory.registerread({string marea, number addr|ADDRESS addrobj},
7467 \begin_layout Itemize
7468 Syntax: function memory.registerwrite({string marea, number addr|ADDRESS
7469 addrobj}, function fn);
7472 \begin_layout Itemize
7473 Syntax: function memory.registerexec({string marea, number addr|ADDRESS addrobj},
7477 \begin_layout Itemize
7478 Syntax: none memory.unregisterread({string marea, number addr|ADDRESS addrobj},
7482 \begin_layout Itemize
7483 Syntax: none memory.unregisterwrite({string marea, number addr|ADDRESS addrobj},
7487 \begin_layout Itemize
7488 Syntax: none memory.unregisterexec({string marea, number addr|ADDRESS addrobj},
7492 \begin_layout Standard
7493 Add or remove callback on memory read, write or execute (depending on the
7495 <addr> is relative to <marea>.
7496 <fn> is the callback.
7497 The register* functions return <fn> (which can then be passed to unregister*
7501 \begin_layout Itemize
7502 Not all cores support this, and it may be unsupported for some memory areas.
7505 \begin_layout Itemize
7506 The functions are passed two parameters: Address and value.
7509 \begin_layout Subsection
7510 memory.{,un}registertrace: Set/Clear trace hook
7513 \begin_layout Itemize
7514 Syntax: function memory.registertrace(number processor, function fn);
7517 \begin_layout Itemize
7518 Syntax: none memory.unregistertrace(number processor, function fn);
7521 \begin_layout Standard
7522 Add or remove trace callback.
7523 <processor> is system-dependent processor number (0 is usually main CPU).
7524 The function arguments work like in other (un)register* functions.
7527 \begin_layout Itemize
7528 The functions are passed two parameters: Trace CPU and Trace event string.
7531 \begin_layout Subsection
7532 memory.cheat: Set cheat
7535 \begin_layout Itemize
7536 Syntax: none memory.cheat({string marea, number addr|ADDRESS addrobj}, number
7540 \begin_layout Itemize
7541 Syntax: none memory.cheat({string marea, number addr|ADDRESS addrobj});
7544 \begin_layout Standard
7545 Set or clear cheat (value <value>) on address <addr> (relative to <marea>).
7546 If <value> is not speicified, clear a cheat.
7549 \begin_layout Itemize
7550 Not all cores support this, and it may be unsupported for some memory areas.
7553 \begin_layout Subsection
7554 memory.setxmask: Set global execute hook mask
7557 \begin_layout Itemize
7558 Syntax: none memory.setxmask(number mask)
7561 \begin_layout Standard
7562 Set the global execute hook mask to <mask>.
7563 The meaning of each bit is system-dependent, but bit 0 should be the main
7567 \begin_layout Subsection
7568 memory.getregister: Get register value
7571 \begin_layout Itemize
7572 Syntax: number/boolean memory.getregister(string register)
7575 \begin_layout Standard
7576 Get the value of named register.
7579 \begin_layout Subsection
7580 memory.getregisters: Get register values
7583 \begin_layout Itemize
7584 Syntax: table memory.getregisters()
7587 \begin_layout Standard
7588 Get the value of all known registers as table.
7591 \begin_layout Subsection
7592 memory.setregister: Set register value
7595 \begin_layout Itemize
7596 Syntax: none memory.setregister(string register, number/boolean value)
7599 \begin_layout Standard
7600 Set the value of named register.
7603 \begin_layout Subsection
7604 memory.mmap: Class MMAP_STRUCT
7607 \begin_layout Standard
7608 See class MMAP_STRUCT
7611 \begin_layout Standard
7612 \begin_inset Newpage pagebreak
7618 \begin_layout Section
7622 \begin_layout Standard
7623 Contains newer memory functions.
7626 \begin_layout Subsection
7627 memory2(): Get all memory area names.
7630 \begin_layout Itemize
7631 Syntax: table memory2()
7634 \begin_layout Standard
7635 Returns array of all valid memory area names.
7638 \begin_layout Subsection
7639 memory2.<marea>:info: Get memory area info
7642 \begin_layout Itemize
7643 Syntax: table memory2.<marea>:info()
7646 \begin_layout Standard
7647 Return table describing given memory area.
7648 Includes fields address, size, last, readonly, special and endian.
7651 \begin_layout Subsection
7652 memory2.<marea>:<op>: Read/Write memory
7655 \begin_layout Itemize
7656 Syntax: none memory2.<marea>:<op>(number offset, number value)
7659 \begin_layout Itemize
7660 Syntax: number memory2.<marea>:<op>(number offset)
7663 \begin_layout Standard
7664 Read/Write value from/to given memory area <marea> at given offset <offset>
7666 The value written is <value>.
7667 <Op> is of form: [i][s]<type>, where:
7670 \begin_layout Itemize
7671 <type> is one of 'byte', 'word', 'hword', 'dword', 'qword', 'float', 'double'.
7674 \begin_layout Itemize
7675 'i' signifies that the value is treated as opposite-to-normal endianess,
7678 \begin_layout Itemize
7679 's' signifies that value is treated as signed (not available for floating-point).
7682 \begin_layout Subsection
7683 memory2.<marea>:read: Scatter-gather value read
7686 \begin_layout Itemize
7687 Syntax: number memory2.<marea>:read(number addr...)
7690 \begin_layout Standard
7691 Read value from given memory area <marea> at byte offsets <addr>..., given
7692 in order of increasing significance.
7693 Value of true and false are special.
7694 True increments address by 1, and false decrements address by 1.
7697 \begin_layout Subsection
7698 memory2.<marea>:sread: Signed scatter-gather value read
7701 \begin_layout Itemize
7702 Syntax: number memory2.<marea>:sread(number addr...)
7705 \begin_layout Standard
7706 Like memory2.<marea>:read, but reads signed values.
7709 \begin_layout Subsection
7710 memory2.<marea>:write: Scatter-gather value write
7713 \begin_layout Itemize
7714 Syntax: number memory2.<marea>:write(number val, number addr...)
7717 \begin_layout Standard
7718 Write value <val> to given memory area <marea> at byte offsets <addr>..., given
7719 in order of increasing significance.
7720 Value of true and false are special.
7721 True increments address by 1, and false decrements address by 1.
7724 \begin_layout Subsection
7725 memory2.<marea>:cheat: Set/Clear cheat
7728 \begin_layout Itemize
7729 Syntax: none memory2.<marea>:cheat(number addr, [number value])
7732 \begin_layout Standard
7733 Set/Clear cheat at offset <addr> of memory area <marea>.
7734 If <value> is given, cheat with specified value is set.
7735 Otherwise cheat on address is removed.
7738 \begin_layout Subsection
7739 memory2.<marea>:sha256: SHA-256
7742 \begin_layout Itemize
7743 Syntax: string memory2.<marea>:sha256(number addr, number size[, number rows,
7747 \begin_layout Standard
7748 Compute SHA-256 of <rows> (default 1) chunks of <size> bytes each, starting
7749 from offset <addr> of area <marea>.
7750 The chunks are separated by <stride>.
7753 \begin_layout Subsection
7754 memory2.<marea>:skein: Skein-512-256
7757 \begin_layout Itemize
7758 Syntax: string memory2.<marea>:skein(number addr, number size[, number rows,
7762 \begin_layout Standard
7763 Same as memory2.<marea>:sha256, except with Skein-512-256 as hash function.
7766 \begin_layout Subsection
7767 memory2.<marea>:store{,cmp}: Copy region to Lua memory with compare
7770 \begin_layout Itemize
7771 Syntax: none memory2.<marea>:store(number addr, number daddr, number size[,
7772 number rows, number stride])
7775 \begin_layout Itemize
7776 Syntax: boolean memory2.<marea>:storecmp(number addr, number daddr, number
7777 size[, number rows, number stride])
7780 \begin_layout Standard
7781 Copy <rows> (default 1) chunks of <size> bytes each, starting from offset
7782 <addr> of area <marea>.
7783 The chunks are separated by <stride>.
7784 The target is Lua host memory, starting from offset <daddr>.
7787 \begin_layout Standard
7788 Additionally, the storecmp method returns false if target was modified (otherwis
7792 \begin_layout Subsection
7793 memory2.<marea>:readregion: Read region
7796 \begin_layout Itemize
7797 Syntax table memory2.<marea>:readregion(number addr, number size)
7800 \begin_layout Standard
7801 Read <size> bytes starting from <addr> in <marea> and return as array.
7804 \begin_layout Subsection
7805 memory2.<marea>:writeregion: Write region
7808 \begin_layout Itemize
7809 Syntax none memory2.<marea>:writeregion(number addr, table data)
7812 \begin_layout Standard
7813 Write array <data> to bytes starting from <addr> in <marea>.
7816 \begin_layout Subsection
7817 memory2.<marea>:register{read,write,exec}: Register hook
7820 \begin_layout Itemize
7821 Syntax: function memory2.<marea>:registerread(number addr, function fn);
7824 \begin_layout Itemize
7825 Syntax: function memory2.<marea>:registerwrite(number addr, function fn);
7828 \begin_layout Itemize
7829 Syntax: function memory2.<marea>:registerexec(number addr, function fn);
7832 \begin_layout Standard
7833 Register debug callback <fn> of specified type at offset <addr> of memory
7838 \begin_layout Subsection
7839 memory2.<marea>:unregister{read,write,exec}: Unregister hook
7842 \begin_layout Itemize
7843 Syntax: none memory2.<marea>:unregisterread(number addr, function fn);
7846 \begin_layout Itemize
7847 Syntax: none memory2.<marea>:unregisterwrite(number addr, function fn);
7850 \begin_layout Itemize
7851 Syntax: none memory2.<marea>:unregisterexec(number addr, function fn);
7854 \begin_layout Standard
7855 Unregister debug callback <fn> of specified type at offset <addr> of memory
7859 \begin_layout Standard
7860 \begin_inset Newpage pagebreak
7866 \begin_layout Section
7870 \begin_layout Standard
7871 Contains random number generation methods.
7872 These functions do not return reproducable results.
7875 \begin_layout Subsection
7876 random.boolean: Random boolean
7879 \begin_layout Itemize
7880 Syntax: boolean random.boolean()
7883 \begin_layout Standard
7884 Returns true or false at random (50-50 chance).
7887 \begin_layout Subsection
7888 random.integer: Random integer
7891 \begin_layout Itemize
7892 Syntax: number random.integer(number highplusone)
7895 \begin_layout Itemize
7896 Syntax: number random.integer(number low, number high)
7899 \begin_layout Standard
7900 With one argument, return random integer [0,<highplusone>) (upper end exclusive).
7901 With two arguments, return random integer [<low>,<high>] (both ends inclusive).
7904 \begin_layout Standard
7905 The returned numbers are from uniform distribution.
7908 \begin_layout Subsection
7909 random.float: Random float
7912 \begin_layout Itemize
7913 Syntax: number random.float()
7916 \begin_layout Standard
7917 Returns random decimal number [0,1).
7920 \begin_layout Subsection
7921 random.among: Random parameter
7924 \begin_layout Itemize
7925 Syntax: value random.among(value values...)
7928 \begin_layout Standard
7929 Returns random parameter value, picked at uniform.
7930 Multiple equivalent values are returned with higher chance.
7933 \begin_layout Subsection
7934 random.amongtable: Random from table
7937 \begin_layout Itemize
7938 Syntax: value random.amongtable(table tab)
7941 \begin_layout Standard
7942 Returns random value from table <tab>.
7943 As in random.among, no equality testing is done.
7946 \begin_layout Standard
7947 \begin_inset Newpage pagebreak
7953 \begin_layout Section
7957 \begin_layout Subsection
7958 zip.enumerate: Enumerate members in zipfile
7961 \begin_layout Itemize
7962 Syntax: Table zip.enumerate(string filename[, boolean invert])
7965 \begin_layout Standard
7966 Returns table of files in zip archive <filename>.
7967 If <invert> is true, instead of returning array of names, returns table
7968 with keys being member names and values being true.
7971 \begin_layout Subsection
7972 zip.writer: Class ZIPWRITER
7975 \begin_layout Standard
7976 See class ZIPWRITER.
7979 \begin_layout Standard
7980 \begin_inset Newpage pagebreak
7986 \begin_layout Section
7990 \begin_layout Standard
7991 Various callback-related functions.
7994 \begin_layout Subsection
7995 \begin_inset CommandInset label
7997 name "sub:callback.register:-Register-a"
8001 callback.register: Register a callback
8004 \begin_layout Itemize
8005 Syntax: function callback.register(string cbname, function cbfun);
8008 \begin_layout Standard
8009 Instruct function <cbfun> to be added to list of callbacks to call on event
8010 <cbname> (See section
8011 \begin_inset CommandInset ref
8013 reference "sec:Callbacks"
8018 The callback name does not have the 'on_' prefix (e.g.
8020 \begin_inset Quotes eld
8024 \begin_inset Quotes erd
8031 \begin_layout Subsection
8032 \begin_inset CommandInset label
8034 name "sub:callback.unregister:-Unregister-"
8038 callback.unregister: Unregister a callback
8041 \begin_layout Itemize
8042 Syntax: function callback.unregister(string cbname, function cbfun);
8045 \begin_layout Standard
8046 Instruct function <cbfun> to be removed from list of callbacks to call on
8050 \begin_layout Subsection
8051 callback.<cbname>:register: Register callback
8054 \begin_layout Itemize
8055 Syntax: function callback.<cbname>:register(function cbfun)
8058 \begin_layout Standard
8059 Synonym for callback.register (section
8060 \begin_inset CommandInset ref
8062 reference "sub:callback.register:-Register-a"
8066 ), albeit with callback name specified differently.
8069 \begin_layout Subsection
8070 callback.<cbname>:unregister: Register callback
8073 \begin_layout Itemize
8074 Syntax: function callback.<cbname>:unregister(function cbfun)
8077 \begin_layout Standard
8078 Synonym for callback.unregister (section
8079 \begin_inset CommandInset ref
8081 reference "sub:callback.unregister:-Unregister-"
8085 ), albeit with callback name specified differently.
8088 \begin_layout Section
8092 \begin_layout Standard
8093 Various bsnes-specific functions.
8096 \begin_layout Subsection
8097 bsnes.dump_sprite: Dump a sprite
8100 \begin_layout Itemize
8101 Syntax: BITMAP bsnes.dump_sprite(string marea, number addr, number width,
8102 number height[, number stride])
8105 \begin_layout Standard
8106 Dumps given sprite (in native format) from memory.
8107 memory area is usually
8108 \begin_inset Quotes eld
8112 \begin_inset Quotes erd
8116 <Width> and <height> are given in 8x8 blocks.
8117 <Stride> overrides row stride (default 512).
8120 \begin_layout Subsection
8121 bsnes.dump_palette: Dump a palette
8124 \begin_layout Itemize
8125 Syntax: PALETTE bsnes.dump_palette(string marea, number addr, bool full256,
8129 \begin_layout Standard
8130 Dumps a palette from memory.
8131 memory area is usually
8132 \begin_inset Quotes eld
8136 \begin_inset Quotes erd
8140 If <full256> is true, 256 colors are dumped (otherwise 16).
8141 If <first_trans> is true, first color is forced transparent.
8144 \begin_layout Subsection
8145 bsnes.enablelayer: Set layer visibility
8148 \begin_layout Itemize
8149 Syntax: none bsnes.enablelayer(number layer, number priority, boolean enabled)
8152 \begin_layout Standard
8153 Enable or disable specified layer at specified priority.
8156 \begin_layout Subsection
8157 bsnes.redump_sprite: Redump a sprite
8160 \begin_layout Itemize
8161 Syntax: none bsnes.redump_sprite(BITMAP bitmap, string marea, number addr[,
8165 \begin_layout Standard
8166 Like bsnes.dump_sprite, but instead dumps to specified bitmap <bitmap>.
8167 The specified bitmap must have size multiple of 8x8.
8170 \begin_layout Subsection
8171 bsnes.redump_palette: Redump a palette
8174 \begin_layout Itemize
8175 Syntax: none bsnes.dump_palette(PALETTE pal, string marea, number addr, bool
8179 \begin_layout Standard
8180 Like bsnes.dump_palette, but instead dumps to specified palette <pal>.
8181 The specified palette must have either 16 or 256 colors.
8184 \begin_layout Section
8185 extensions to table string
8188 \begin_layout Subsection
8189 string.charU: string.char, UTF-8 version.
8192 \begin_layout Itemize
8193 Syntax: string string.charU(number n...)
8196 \begin_layout Standard
8197 Like Lua string.char(), but works in terms of Unicode codepoints.
8198 The returned string is UTF-8.
8201 \begin_layout Subsection
8202 string.byteU: string.byte, UTF-8 version.
8205 \begin_layout Itemize
8207 string.byteU(string str[, number i[, number j]])
8210 \begin_layout Standard
8211 Like string.byte(), but works in terms of Unicode codepoints.
8212 The input string <str> is assumed UTF-8.
8215 \begin_layout Subsection
8216 string.regex: Match string against regular expression
8219 \begin_layout Itemize
8220 Syntax: boolean/string...
8221 string.regex(string regexp, string against)
8224 \begin_layout Standard
8225 Match POSIX-extended regular expression <regexp> against string <against>.
8226 If no match, false is returned.
8227 Otherwise if string has no subcaptures, true is returned.
8228 Otherwise each subcapture is returned as a string (in order of starting
8232 \begin_layout Subsection
8233 string.hex: Transform integer into hex string
8236 \begin_layout Itemize
8237 Syntax: string string.hex(number n, [number digits])
8240 \begin_layout Standard
8241 Returns hexadecimal string representation of <n>, optionally padded with
8242 zeroes to <digits> digits (default is not to pad).
8245 \begin_layout Subsection
8246 string.lpad: Pad string with spaces from left
8249 \begin_layout Itemize
8250 Syntax: string string.lpad(string x, number n)
8253 \begin_layout Standard
8254 Pad string <x> to <n> bytes by inserting spaces at start and return the
8258 \begin_layout Subsection
8259 string.rpad: Pad string with spaces from right
8262 \begin_layout Itemize
8263 Syntax: string string.rpad(string x, number n)
8266 \begin_layout Standard
8267 Pad string <x> to <n> bytes by inserting spaces at end and return the result.
8270 \begin_layout Section
8274 \begin_layout Standard
8275 Contains copy of global variables from time of Lua initialization.
8279 \begin_layout Standard
8280 \begin_inset Newpage pagebreak
8286 \begin_layout Section
8287 \begin_inset CommandInset label
8289 name "sec:Callbacks"
8296 \begin_layout Standard
8297 Various callbacks to Lua that can occur.
8300 \begin_layout Subsection
8301 on_paint: Screen is being painted
8304 \begin_layout Itemize
8305 Callback: on_paint(bool not_synth)
8308 \begin_layout Standard
8309 Called when screen is being painted.
8310 Any gui.* calls requiring graphic context draw on the screen.
8313 \begin_layout Itemize
8314 not_synth is true if this hook is being called in response to received frame,
8318 \begin_layout Subsection
8319 on_video: Dumped video frame is being painted
8322 \begin_layout Itemize
8323 Callback: on_video()
8326 \begin_layout Standard
8327 Called when video dump frame is being painted.
8328 Any gui.* calls requiring graphic context draw on the video.
8331 \begin_layout Subsection
8332 on_frame_emulated: Frame emulation complete
8335 \begin_layout Itemize
8336 Callback: on_frame_emulated()
8339 \begin_layout Standard
8340 Called when emulating frame has completed and on_paint()/on_video() calls
8341 are about to be issued.
8344 \begin_layout Subsection
8345 on_frame: Frame emulation starting.
8348 \begin_layout Itemize
8349 Callback: on_frame()
8352 \begin_layout Standard
8353 Called on each starting whole frame.
8356 \begin_layout Subsection
8357 on_rewind: Movie rewound to beginning
8360 \begin_layout Itemize
8361 Callback: on_rewind()
8364 \begin_layout Standard
8365 Called when rewind movie to beginning has completed.
8368 \begin_layout Subsection
8369 on_pre_load: Load operation is about to start
8372 \begin_layout Itemize
8373 Callback: on_pre_load(string name)
8376 \begin_layout Standard
8377 Called just before savestate/movie load occurs (note: loads are always delayed,
8378 so this occurs even when load was initiated by lua).
8381 \begin_layout Subsection
8382 on_err_Load: Load failed
8385 \begin_layout Itemize
8386 Callback: on_err_load(string name)
8389 \begin_layout Standard
8390 Called if loadstate goes wrong.
8393 \begin_layout Subsection
8394 on_post_load: Load completed
8397 \begin_layout Itemize
8398 Callback: on_post_load(string name, boolean was_savestate)
8401 \begin_layout Standard
8402 Called on successful loadstate.
8403 was_savestate gives if this was a savestate or a movie.
8406 \begin_layout Subsection
8407 on_pre_save: Save operation is about to start
8410 \begin_layout Itemize
8411 Callback: on_pre_save(string name, boolean is_savestate)
8414 \begin_layout Standard
8415 Called just before savestate save occurs (note: movie saves are synchronous
8416 and won't trigger these callbacks if called from Lua).
8419 \begin_layout Subsection
8420 on_err_save: Save failed
8423 \begin_layout Itemize
8424 Callback: on_err_save(string name)
8427 \begin_layout Standard
8428 Called if savestate goes wrong.
8431 \begin_layout Subsection
8432 on_post_save: Save completed
8435 \begin_layout Itemize
8436 Callback: on_post_save(string name, boolean is_savestate)
8439 \begin_layout Standard
8440 Called on successful savaestate.
8441 is_savestate gives if this was a savestate or a movie.
8444 \begin_layout Subsection
8445 on_quit: Emulator is shutting down
8448 \begin_layout Itemize
8452 \begin_layout Standard
8453 Called when emulator is shutting down.
8456 \begin_layout Subsection
8457 on_input: Polling for input
8460 \begin_layout Standard
8461 Called when emulator is just sending input to bsnes core.
8462 Warning: This is called even in readonly mode, but the results are ignored.
8465 \begin_layout Subsection
8466 on_reset: System has been reset
8469 \begin_layout Itemize
8470 Callback: on_reset()
8473 \begin_layout Standard
8474 Called when system is reset.
8477 \begin_layout Subsection
8478 on_readwrite: Entered recording mode
8481 \begin_layout Itemize
8482 Callback: on_readwrite()
8485 \begin_layout Standard
8486 Called when moving into recording mode as result of
8487 \begin_inset Quotes eld
8491 \begin_inset Quotes erd
8494 command (note: moving to rwmode by Lua won't trigger this, as per recursive
8498 \begin_layout Subsection
8499 on_snoop/on_snoop2: Snoop core controller reads
8502 \begin_layout Itemize
8503 Callback: on_snoop(number port, number controller, number index, number
8507 \begin_layout Itemize
8508 Callback: on_snoop2(number port, number controller, number index, number
8512 \begin_layout Standard
8513 Called each time bsnes asks for input.
8514 The value is the final value to be sent to bsnes core (readonly mode, autohold
8515 and autofire have been taken into account).
8516 Might be useful when translating movies to format suitable for console
8518 Note: There is no way to modify the value to be sent.
8521 \begin_layout Itemize
8522 On_snoop2 is called instead of on_snoop if defined.
8523 Reserves port 0 for system, having first user port be port 1.
8526 \begin_layout Subsection
8527 on_keyhook: Hooked key/axis has been moved
8530 \begin_layout Itemize
8531 Callback: on_keyhook(string keyname, table state)
8534 \begin_layout Standard
8535 Sent when key that has keyhook events requested changes state.
8536 Keyname is name of the key (group) and state is the state (same kind as
8537 table values in input.raw).
8540 \begin_layout Subsection
8544 \begin_layout Itemize
8548 \begin_layout Standard
8549 Called when requested by set_idle_timeout(), the timeout has expired and
8550 emulator is waiting.
8553 \begin_layout Subsection
8554 on_timer: Timer event
8557 \begin_layout Itemize
8558 Callback: on_timer()
8561 \begin_layout Standard
8562 Called when requested by set_idle_timeout() and the timeout has expired
8563 (regardless if emulator is waiting).
8566 \begin_layout Subsection
8567 on_set_rewind: Rewind point has been set
8570 \begin_layout Itemize
8571 Callback: on_set_rewind(UNSAFEREWIND r)
8574 \begin_layout Standard
8575 Called when unsafe rewind object has been constructed.
8578 \begin_layout Subsection
8579 on_pre_rewind: Rewind is about to occur
8582 \begin_layout Itemize
8583 Callback: on_pre_rewind()
8586 \begin_layout Standard
8587 Called just before unsafe rewind is about to occur.
8590 \begin_layout Subsection
8591 on_post_rewind: Rewind has occured
8594 \begin_layout Itemize
8595 Callback: on_post_rewind()
8598 \begin_layout Standard
8599 Called just after unsafe rewind has occured.
8602 \begin_layout Subsection
8603 on_button: Button has been pressed
8606 \begin_layout Itemize
8607 Callback: on_button(number port, number controller, number index, string
8611 \begin_layout Standard
8612 Called on controller button press, with following parameters:
8615 \begin_layout Itemize
8616 port: Port number (0 is system)
8619 \begin_layout Itemize
8620 controller: Controller within port
8623 \begin_layout Itemize
8624 index: Index of button.
8627 \begin_layout Itemize
8628 type: Type of event, one of:
8632 \begin_layout Itemize
8633 \begin_inset Quotes eld
8637 \begin_inset Quotes erd
8640 : Button was pressed.
8643 \begin_layout Itemize
8644 \begin_inset Quotes eld
8648 \begin_inset Quotes erd
8651 : Button was released.
8654 \begin_layout Itemize
8655 \begin_inset Quotes eld
8659 \begin_inset Quotes erd
8665 \begin_layout Itemize
8666 \begin_inset Quotes eld
8670 \begin_inset Quotes erd
8673 : Released from hold.
8676 \begin_layout Itemize
8677 \begin_inset Quotes eld
8681 \begin_inset Quotes erd
8684 : Typing input on button.
8687 \begin_layout Itemize
8688 \begin_inset Quotes eld
8692 \begin_inset Quotes erd
8695 : Typing input undone.
8698 \begin_layout Itemize
8699 \begin_inset Quotes eld
8702 autofire <duty> <cycle>
8703 \begin_inset Quotes erd
8706 : Autofire with specifie duty and cycle.
8709 \begin_layout Itemize
8710 \begin_inset Quotes eld
8714 \begin_inset Quotes erd
8720 \begin_layout Itemize
8721 \begin_inset Quotes eld
8725 \begin_inset Quotes erd
8728 : Analog action on axis.
8732 \begin_layout Subsection
8733 on_movie_lost: Movie data is about to be lost
8736 \begin_layout Itemize
8737 Callback: on_movie_lost(STRING kind)
8740 \begin_layout Standard
8741 Called just before something would happen that could lose movie data.
8745 \begin_layout Itemize
8746 readwrite: Switching to recording mode.
8749 \begin_layout Itemize
8750 reload: ROM is being reloaded in recording mode.
8753 \begin_layout Itemize
8754 load: New movie is being loaded.
8757 \begin_layout Itemize
8758 unsaferewind: Unsafe rewind is happening.
8761 \begin_layout Subsection
8762 on_latch: Latch line is rising
8765 \begin_layout Itemize
8766 Callback: on_latch(<core-dependent-parameters>)
8769 \begin_layout Standard
8770 Called when latch line for controller is rising.
8771 Some cores may not support this.
8774 \begin_layout Section
8775 System-dependent behaviour
8778 \begin_layout Subsection
8782 \begin_layout Itemize
8783 Registers are: pbpc, pb, pc, r0, r1, r2, r3, r4, r5, a, x, y, z, s, d, db,
8784 p, e, irq, wai, mdr, vector, aa, rd, sp, dp, p_n, p_v, p_m, p_x, p_d, p_i,
8785 p_z, p_c, ppu_display_disabled, ppu_oam_priority, ppu_bg_tilesize[0], ppu_bg_ti
8786 lesize[1], ppu_bg_tilesize[2], ppu_bg_tilesize[3], ppu_bg3_priority, ppu_mosaic_
8787 enabled[0], ppu_mosaic_enabled[1], ppu_mosaic_enabled[2], ppu_mosaic_enabled[3],
8788 ppu_vram_incmode, ppu_mode7_vflip, ppu_mode7_hflip, ppu_window1_enabled[0],
8789 ppu_window1_enabled[1], ppu_window1_enabled[2], ppu_window1_enabled[3],
8790 ppu_window1_enabled[4], ppu_window1_enabled[5], ppu_window1_invert[0],
8791 ppu_window1_invert[1], ppu_window1_invert[2], ppu_window1_invert[3], ppu_window
8792 1_invert[4], ppu_window1_invert[5], ppu_window2_enabled[0], ppu_window2_enabled[
8793 1], ppu_window2_enabled[2], ppu_window2_enabled[3], ppu_window2_enabled[4],
8794 ppu_window2_enabled[5], ppu_window2_invert[0], ppu_window2_invert[1], ppu_windo
8795 w2_invert[2], ppu_window2_invert[3], ppu_window2_invert[4], ppu_window2_invert[5
8796 ], ppu_bg_enabled[0], ppu_bg_enabled[1], ppu_bg_enabled[2], ppu_bg_enabled[3],
8797 ppu_bg_enabled[4], ppu_bgsub_enabled[0], ppu_bgsub_enabled[1], ppu_bgsub_enable
8798 d[2], ppu_bgsub_enabled[3], ppu_bgsub_enabled[4], ppu_window_enabled[0],
8799 ppu_window_enabled[1], ppu_window_enabled[2], ppu_window_enabled[3], ppu_window
8800 _enabled[4], ppu_sub_window_enabled[0], ppu_sub_window_enabled[1], ppu_sub_windo
8801 w_enabled[2], ppu_sub_window_enabled[3], ppu_sub_window_enabled[4], ppu_addsub_m
8802 ode, ppu_direct_color, ppu_color_mode, ppu_color_halve, ppu_color_enabled[0],
8803 ppu_color_enabled[1], ppu_color_enabled[2], ppu_color_enabled[3], ppu_color_ena
8804 bled[4], ppu_color_enabled[5], ppu_mode7_extbg, ppu_pseudo_hires, ppu_overscan,
8805 ppu_oam_interlace, ppu_interlace, ppu_latch_hcounter, ppu_latch_vcounter,
8806 ppu_counters_latched, ppu_time_over, ppu_range_over, ppu_ppu1_mdr, ppu_ppu2_mdr
8807 , ppu_bg_y[0], ppu_bg_y[1], ppu_bg_y[2], ppu_bg_y[3], ppu_ioamaddr, ppu_icgramad
8808 dr, ppu_display_brightness, ppu_oam_basesize, ppu_oam_nameselect, ppu_oam_tdaddr
8809 , ppu_oam_baseaddr, ppu_oam_addr, ppu_oam_firstsprite, ppu_oam_latchdata,
8810 ppu_bg_mode, ppu_mosaic_size, ppu_mosaic_countdown, ppu_bg_scaddr[0], ppu_bg_sc
8811 addr[1], ppu_bg_scaddr[2], ppu_bg_scaddr[3], ppu_bg_scsize[0], ppu_bg_scsize[1],
8812 ppu_bg_scsize[2], ppu_bg_scsize[3], ppu_bg_tdaddr[0], ppu_bg_tdaddr[1],
8813 ppu_bg_tdaddr[2], ppu_bg_tdaddr[3], ppu_bg_ofslatch, ppu_m7_hofs, ppu_m7_vofs,
8814 ppu_bg_hofs[0], ppu_bg_hofs[1], ppu_bg_hofs[2], ppu_bg_hofs[3], ppu_bg_vofs[0],
8815 ppu_bg_vofs[1], ppu_bg_vofs[2], ppu_bg_vofs[3], ppu_vram_mapping, ppu_vram_incs
8816 ize, ppu_vram_addr, ppu_mode7_repeat, ppu_m7_latch, ppu_m7a, ppu_m7b, ppu_m7c,
8817 ppu_m7d, ppu_m7x, ppu_m7y, ppu_cgram_addr, ppu_cgram_latchdata, ppu_window1_lef
8818 t, ppu_window1_right, ppu_window2_left, ppu_window2_right, ppu_window_mask[0],
8819 ppu_window_mask[1], ppu_window_mask[2], ppu_window_mask[3], ppu_window_mask[4],
8820 ppu_window_mask[5], ppu_color_mask, ppu_colorsub_mask, ppu_color_r, ppu_color_g
8821 , ppu_color_b, ppu_color_rgb, ppu_scanlines, ppu_hcounter, ppu_vcounter,
8822 ppu_vram_readbuffer, ppu_oam_itemcount, ppu_oam_tilecount,
8825 \begin_layout Itemize
8826 on_latch has no parameters
8829 \begin_layout Itemize
8830 CPU 0 is S-CPU, 1 is S-SMP.
8833 \begin_layout Itemize
8834 Cheats are supported for ROM, SRAM, WRAM, BSXFLASH, SLOT{A,B}_{RAM,ROM}.
8837 \begin_layout Itemize
8838 Read/Write/Execute hooks are supported for ROM, SRAM, WRAM, BSXFLASH, SLOT{A,B}_
8842 \begin_layout Itemize
8843 Memory areas are: WRAM, APURAM, VRAM, OAM, CGRAM, RTC, DSPRAM, DSPPROM,
8844 DSPDROM, SRAM, ROM, BUS, PTRTABLE, CPU_STATE, PPU_STATE, SMP_STATE, DSP_STATE,
8845 BSXFLASH, BSX_RAM, BSX_PRAM, SLOTA_ROM, SLOTB_ROM, SLOTA_RAM, SLOTB_RAM,
8846 GBCPU_STATE, GBROM, GBRAM, GBWRAM, GBHRAM.
8849 \begin_layout Subsection
8853 \begin_layout Itemize
8854 Registers are: wrambank, cyclecounter, pc, sp, hf1, hf2, zf, cf, a, b, c,
8858 \begin_layout Itemize
8859 on_latch is not supported
8862 \begin_layout Itemize
8866 \begin_layout Itemize
8867 Cheats are supported for ROM, SRAM and WRAM.
8870 \begin_layout Itemize
8871 Read/Write/Execute hooks are supported for ROM (read/execute only), SRAM
8875 \begin_layout Itemize
8876 Memory areas are: SRAM, WRAM, VRAM, IOAMHRAM, ROM, BUS.