· 9 years ago · Dec 23, 2016, 11:41 PM
1//Docs for 2.54 Beta
2//Rev. 0.8.9
3//for 2.54 b40
4//16th December, 2016
5
6Search for !#! to find areas that require completion.
7?REFFFC? What is this?
8
9//===================================================================================
10// --- ZScript built-in functions and variables ---
11//===================================================================================
12/*
13* These functions are all INTERNAL to ZQuest. They require no header
14* or other import directives to work, and are all direct representations
15* of ZASM instructions.
16*
17* These functions and commands are the BASIC BUILDING BLOCKS of ZScript:
18* While they require no other functions to work, ALL other functions
19* in headers (such as std.zh) RELY, and OPERATE using these functions.
20*
21* Thus, it is essential to know what each of these does, how they work,
22* and how to use them.
23*
24* For other included functions, that are not internal (i.e. external functions)
25* please read the documentation specific to each header. These are individual
26* files (e.g. std.txt), however if you wish to view all the pre-packaged ZScript
27* functions, and commands, you may view the EXTENDED DOCUMENTATION, as
28* those documentation files contain all of the 'Essential ZScript' that
29* you will want to use.
30*
31* Where possible, the ZASM instruction used by the functions, and the
32* commands detailed herein are listed inline with the entry for the related
33* function / command. Full (public) ZASM documentation is, sadly incomplete.
34*
35* Note: Functions and variables other than global functions are properties
36* of **objects**. Objects are divided into NAMESPACEs and CLASSes, and the
37* the syntax for using them is:
38*
39* [object name]->[property]
40*
41* where "[object name]" is the object's name (e.g. Link, Game, Screen)/
42* and "[property]" is the function.
43*
44* Example:
45* void GetCurDMap() is a Game property, and is called as:
46*
47* Game->GetCurDMap();
48*
49* "Link", "Screen" and "Game" are always available and don't need to be
50* instantiated, while you must initialise other classes, such as ffc, item,
51* and npc.
52*
53* ZScript functions are of the types: int, float, bool, and void. Of these,
54* only void does not return a value. (The void type is normally used to run
55* a series of instructions, or to set values). The other types retrun values
56* appropriate to their type.
57*
58* Note: In the following, "int" indicates that a parameter is truncated by a
59* function to an integer, or that the return value will always be an integer
60* however, ZScript itself makes no distinction between int and float types.
61*/
62
63/************************************************************************************************************/
64
65//////////////////
66/// ZASM Flags ///
67//////////////////
68
69ZASM uses a series of special flags, to determine how it should follow logical instructions,
70including the following:
71
72SCRIPT FLAGS
73TRUEFLAG : A condition in the script, is true
74MOREFLAG : Must be set manually with ZASM.
75FALSEFLAG : Must be set namually with ZASM.
76LESSFLAG : Must be set manually with ZASM.
77
78Instructions
79SETTRUE : Set the Script Flag TRUEFLAG.
80 SETTRUE Sets a true condition for the Assembler, if a COMPARERV and COMPARER validate.
81 This is used when making statements in ZScript.
82SETFALSE: Set the Script Flag FALSEFLAG: ZScript does not do this.
83SETMORE : Set the Script FLag MOREFLAG: ZScript does not do this.
84SETLESS : Set the Script Flag LESSFLAG: ZScript does not do this.
85
86These flags are used in evaluation instructions, to determine if an instruction should run.
87
88Examples of these are as follows:
89
90GOTOTRUE: Executes the GOTO instruction only if the Script Flag TRUEFLAG is enabled.
91GOTOFALSE: Executes the GOTO instruction only if the Script Flag FALSEFLAG is enabled.
92GOTOMORE: Executes the GOTO instruction only if the Script Flag MOREFLAG is enabled.
93GOTOLESS: Executes the GOTO instruction only if the Script Flag LESSFLAG is enabled.
94
95In contrast, GOTO/GOTOR ignore all flags, and conditions.
96
97ZScript always compiles down to GOTO, GOTOR, and GOTOTRUE instructions.
98The other FLAG-typed GOTO instruction types are valid only in ZASM, and serve no useful purpose.
99GOTOLESS, GOTOMORE, and GOTOFALSE are effectively deprecated.
100
101//=======================================================
102//--- Instruction Processing Order and General Timing ---
103=========================================================
104
1051. Instructions in Global script Init (if starting a new game)
1062. Instructions in Global Script OnContinue (is resuming a game)
1073. Instructions immediately inside the run() function of a global active script.
1084. Instructions in the global active script's infinite loop prior to Waitdraw,
109 if (5) does not exist, or on the first frame of the game.
1105. Instructions from an ffc script positioned after (an illegal)
111 Waitdraw() instruction in that script from the previous frame.
112 Note: Requires being on at least the second frame of a game session.
1136. Instructions in the global active script prior to Waitdraw().
1147. Instructions in an ffc script, other than (5), excluding draw commands.
1158. Screen Scrolling (2.50.2, or later)
1169. Instructions from item scripts.
11710. Waitdraw() in a global active script.
11811. Engine writing to Link->Dir and Link->Tile.
11912. Instructions in the global active script, called after Waitdraw()
12012(b). Screen Scrolling ( 2.50.0, and 2.50.1 )
12113. Drawing from FFCs
12214. Instructions in an OnExit script, if the game is exiting.
12315. Return to (5).
124
125
126//=================
127//--- Pointers ---
128//=================
129
130Global array pointers start at 4096 (when traced). These are added in escalating value, but in the reverse-order
131of declaration. e.g. The last declared array will be ID 4096.
132
133/************************************************************************************************************/
134
135
136////////////////////////
137/// Operator Symbols ///
138////////////////////////
139
140ZScript supports value input as decimal, hexidecimal, and binary.
141
142To input hexidecimal values, preface them with '0x'. Thus, '0x0F' for '16'.
143To input binary balues, end them with a lowercase 'b'. Thus, '11b' for '3'.
144
145Name Sign ZASM (R) ZASM (V) Definition
146PLUS + ADDR<><> ADDV<><> Adds a value a + b, a + 3
147MINUS - SUBR<><> SUBV<><> Subtracts a value a - b, a - 2
148INCREMENT ++ Increments a value by '1'
149DECREMENT -- Decreases a value by '1'
150MULTIPLY * MULTR<><> MULTV<><> Multiplies values a * b
151DIVIDE / DIVR<><> DIVV<><> Divides values a / b
152MODULUS % Returns the remainder of integer division of 4 % 2
153NOT ! NOT<> Inverse logic boolean operator.
154 if ( !var1 == 0 ) returns true if var1 is zero,
155 and false if var1 is non-zero
156EQUALS = SETR<><> SETV<><> Sets a value to another value a = 4
157EXACTLY EQUALS == Compares value a == b and returns if they match.
158NOT EQUALS != Compares values a != b and returns if they do not match,
159LESSTHAN < Comapres a < b and returns if a is less then b.
160MORETHAN > Compares a > b and returns if a is more than b.
161LOGICAL OR || Boolean logic, Or.
162LOGICAL AND && Boolean Logic And.
163
164SET ADDRESS ARG SETA1<><>
165 SETA2<><>
166GET ADDRESS ARG GETA1<><>
167 GETA2<><>
168
169Note: LOGICAL XOR (^^) is not valid in ZScript, but you may simulate it with custom functions.
170
171
172/////////////////////////
173/// Bitwise Operators ///
174/////////////////////////
175
176Reminder: You may reference a binary value using a numeric sequence, ending in 'b':
177 0100010b
178 ('34' decimal)
179
180Or ZScript Symbol ZASM Instructions:
181 | ORV<><>
182 ORR<><>
183
184And ZScript Symbol ZASM Instructions:
185 & ANDR<><>
186 ANDV<><>
187
188Not ZScript Symbol ZASM Instructions:
189 ~ BITNOT<>
190
191Left Shift:
192 ZScript Symbol ZASM Instructions
193 << LSHIFTV<><>
194 LSHIFTR<><>
195
196Right Shift:
197 ZScript Symbol ZASM Instructions
198 >> RSHIFTV<><>
199 RSHIFTR<><>
200
201Xor ZScript Symbol ZASM Instructions:
202 ^ XORV<><>
203 XORR<><>
204
205Nor ZScript Symbol ZASM Instructions:
206 ~| NORV<><>
207 NORR<><>
208
209XNor ZScript Symbol ZASM Instructions:
210 ~^ XNORV<><>
211 XNORV<><>
212
213Nand ZScript Symbol ZASM Instructions:
214 ~& NANDV<><>
215 NANDR<><>
216
217/************************************************************************************************************/
218
219
220//========================
221//--- Global Functions ---
222//========================
223
224/////////////////////////
225/// General Functions ///
226/////////////////////////
227
228
229void Waitdraw(); ZASM Instruction:
230 WAITDRAW
231/**
232* Halts execution of the script until ZC's internal code has been run (movement,
233* collision detection, etc.), but before the screen is drawn. This can only
234* be used in the active global script.
235* Waitdraw() may only be called from the global active script; not from FFC scripts.
236* The sequence of ZC actions is as follows:
237
238* FFCs (in numerical sequence, from FFC 01, to FFC 32)
239* Enemies
240* EWeapons
241* Link
242* LWeapons
243* Hookshot
244* Collision Checking
245* Store Link->Input / Link->Press
246* Waitdraw()
247* Drawing
248* Rendering of the Screen
249* Screen Scrolling
250* Drawing from FFCs
251*
252* Note: Drawing from FFCs technically occurs with other Drawing, but as it is issued after Waitdraw(),
253* it is offset (a frame late) and renders after screen scrolling, and after any other drawing in the same
254* frame as draw instructions from ffcs are called. To ensure that drawing done by ffcs is in sync with
255* other drawing, it is imperative to call it from your global script, using the ffc to trigger global
256* conditions that cause global drawing instructions that are called before Waitdraw() in your global
257* active script to evaluate true.
258*
259* Anything placed after Waitdraw() will not present graphical effects until the next frame.
260* It is possible { ! CHECK } to read/store Link->Tile, Link->Dir and other variables *after* Waitdraw()
261* in one frame, and then use these values to modify other pointer members so that they are drawn correctly
262* at the next execution of Waitdraw().
263*
264*
265*/ Example Use:
266
267 Waitdraw();
268
269//! Submit bug report that Link->Dir and Link->Tile are incorrect before Waitdraw.
270
271*//////////////////////////////
272* Waitdraw() in ffc scripts ///
273* --------------------------///
274* Althouth technically illegal, it is possible to call Waitdraw() in an *ffc script*. Doing this has the
275* following effects, and/or consequences:
276*
277* 1. The Compiler will report an error, and print the error to Allegro log:
278* 'Warning: Waitdraw() may only be used in global scripts.'
279* 2. Any instruction sint he ffc script that are called before the Waitdraw() instruction in the ffc script
280* will run this frame, after Waitdraw() in your global active script.
281* 3. Any instructions called *after* Waitdraw() in the ffc script, will run BEFORE BOTH Waitdraw() in your
282* global active script, and BEFORE any other instructions in your global active script's infinite loop.
283*
284* This behaviour may change in future versions of ZC, and using Waitdraw() in ffc scripts is not advised.
285
286*///////////////////////////////
287* Waitdraw() in item scripts ///
288* ---------------------------///
289* Althouth technically illegal, it is possible to call Waitdraw() in an item sctipt. Doing this has the
290* following effects, and/or consequences:
291*
292* 1. The Compiler will report an error, and print the error to Allegro log:
293* 'Warning: Waitdraw() may only be used in global scripts.'
294* 2.
295*
296* This behaviour may change in future versions of ZC, and using Waitdraw() in item scripts is not advised.
297
298/************************************************************************************************************/
299
300void Waitframe(); ZASM Instruction:
301 WAITFRAME
302/**
303* Temporarily halts execution of the current script. This function returns at
304* the beginning of the next frame of gameplay.
305* Slots 1, 3 and 4 Global scripts and item scripts only execute for one frame,
306* so in those scripts Waitframe() is essentially Quit().
307* It is safe to call Waitframe in the active global script.
308* A Waitframe is required in all infinite loops (e.g. while(true) ) so that ZC may
309* pause to break in order to advance to the next frame, then resume the loop from the start.
310*
311*/ Example Use:
312
313 Waitframe();
314
315*///////////////////////////////
316* Waitdraw() in item scripts ///
317* ---------------------------///
318* Althouth technically legal, it is invalid to call Waitframe() in an item sctipt. Doing this has the
319* following effects, and/or consequences:
320*
321* 1. The script will prematurely exit.
322*
323* Calling Waitframe() in an item script is effectively identical to calling Quit(), however this behaviour
324* may change in future versions of ZC, and using Waitframe() in item scripts is not advised.
325
326/************************************************************************************************************/
327
328void Quit(); ZASM Instruction:
329 QUIT
330/**
331* Terminates execution of the current script. Does not return.
332* Caution: If called from a global script, the script itself exits.
333*
334*/ Example Use:
335
336 Quit();
337
338/************************************************************************************************************/
339
340////////////////////
341/// Modify Tiles ///
342////////////////////
343
344
345void CopyTile(int srctile, int desttile); ZASM Instruction:
346 COPYTILERR d2,d3
347 COPYTILEVV
348 COPYTILERV
349 COPYTILEVR
350/**
351* Copies the tile specified by scrtile onto the tile space
352* specified by desttile. The valid tile value range is 0 to 65519.
353* This change is temporary within the quest file
354* and not be retained when saving the game.
355*
356*/ Example Use:
357
358 CopyTile(312,11614);
359 Copies tile 312, to tile 11614. Tiles 312, and 11614 will be identical.
360
361/** TIP **
362* CopyTile may be used to change Link's tile, by copying a tile onto whatever tile ZC is
363* using as a source for Link->Tile
364* Thus, although you cannot write directly to Link->Tile, you can write to the actual tile
365* that is being used for this Link attribute, and you can do this for any other game graphic
366* that you need to change.
367*
368* When doing this, it is important to read Link->Dir or Link->Flip, *after* Waitdraw() and
369* perform the CopyTile() operation immediately thereafter.
370*/
371
372/************************************************************************************************************/
373
374void SwapTile(int firsttile, int secondtile); ZASM Instruction:
375 SWAPTILERR d2,d3
376 SWAPTILEVV
377 SWAPTILEVR
378 SWAPTILERV
379/**
380* Swaps the two tiles specified by firsttile and secondtile.
381* The valid tile value range is 0 to 65519.
382* This change is *TEMPORARY* within the quest file
383* and will not be retained when saving the game.
384*
385*/ Example Use:
386
387SwapTile(312,11614);
388Changes tile 11614 into tile 312; and tile 312 into tile 11614, transposing their positions.
389
390/************************************************************************************************************/
391
392void OverlayTile(int firsttile, int secondtile); ZASM Instruction:
393 OVERLAYTILEVV
394 OVERLAYTILEVR
395 OVERLAYTILERV
396 OVERLAYTILERR
397/**
398* Overlays secondtile onto firsttile, ignoring all pixels of colour 0.
399* The valid tile value range is 0 to 65519.
400* This change is *TEMPORARY* within the quest file
401* and will not be retained when saving the game.
402*
403*/ Example Use:
404
405
406/************************************************************************************************************/
407
408void ClearTile(int tileref); ZASM Instruction:
409 CLEARTILER <d3>
410 CLEARTILEV
411/**
412* Erases the tile specified by tileref.
413* This change is temporary within the quest file
414* and will not be retained when saving the game.
415* Tiles are not / are (!check!) shifted upward to adjust for the cleared tile.
416*
417*/ Example Use:
418
419 ClearTile(21362);
420 Clears tile 21362 by ( blanking it to colour 0 ) | ( removing it and shifting all tiles
421 thereafter upward ).
422
423/************************************************************************************************************/
424
425//Overlay Tile
426
427//! Is there a ZScript equivalent of this?!
428//! This instruction seems to be ***ZASM-specific***.
429//! Game->overlayTile() and Screen->OverlayTile() both return an error (no such pointer).
430//! Add this to the bytecode in a future build.
431//! As far as I can tell, this should work from ZASM, but it was never added to the ZScript side. (11/July/2016: ZRPG)
432
433void OverlayTile() ?
434
435 OVERLAYTILEVV
436 OVERLAYTILEVR
437 OVERLAYTILERV
438 OVERLAYTILERR
439
440/************************************************************************************************************/
441
442///////////////
443/// Tracing ///
444///////////////
445
446
447void Trace(float val); ZASM Instruction:
448 TRACER d3
449 TRACEV
450/**
451* Prints a line containing a string representation of val to allegro.log.
452* Useful for debugging scripts. You may trace int, and float types.
453* For b oolean values, see TraceB() below.
454* Values printed to allegro.log no not incorporate any spacing, or carriage
455* returns. You must manually add these into your commands.
456* Int values are not truncated when printed, and will always have four leading
457* zeros after the decimal point.
458* To add new lines (carriange returns), see TraceNL() below.
459*
460*/ Example Use:
461
462 int val = 4;
463 Trace(val);
464 Prints 4.000 to allegro.log
465
466/************************************************************************************************************/
467
468void TraceB(bool state); ZASM Instruction:
469 TRACE2R d3
470 TRACE2V
471/**
472* Prints a boolean state to allegro.log. Works as trace() above, but prints 'true'
473* or 'false' to allegro.log
474*
475*/ Example Use:
476
477 bool test = true;
478 TraceB(test);
479 Prints 'true' to allegro.log.
480
481/************************************************************************************************************/
482
483void TraceToBase( int val, int base, ZASM Instruction:
484 int mindigits ); TRACE3
485/**
486* Prints a line in allegro.log representing 'val' in numerical base 'base',
487* where 2 <= base <= 36, with minimum digits 'mindigits'.
488* (Base must be at least base-2, and at most, base-36)
489* Can be useful for checking hex values or flags ORed together, or just to trace
490* an integer value, as Trace() always traces to four decimal places.
491* mindigits specifies the minimum number of integer digits to print.
492* Unlike Trace(), Decimal values are not printed. TraceToBase *does not* handle floats.
493* If you specify a floating point value as arg 'val', it will be Floored before conversion.
494*
495*/ Example Use:
496
497 TraceToBase(20,8,1);
498 Converts (decimal) d20 to base-8 (o24 in base-8) and prints value '024' to allegro.log
499
500 TraceToBase(50,16,1);
501 Converts (decimal) d50 to base-16 (0x32 hexadecimal) and prints value '0x32' to allegro.log.
502
503/************************************************************************************************************/
504
505void ClearTrace(); ZASM Instruction:
506 TRACE4
507/**
508* Clears allegro.log of all current traces and messages from Zelda Classic/ZQuest.
509* Works on a per-quest, per-session basis. Values recorded from previous sessions are not erased.
510*
511*/ Example Use
512
513 ClearTrace();
514
515/************************************************************************************************************/
516
517void TraceNL(); ZASM Instruction:
518 TRACE5
519/**
520* Traces a newline to allegro.log
521* This inserts a carriage return (as if pressing return/enter) into allegro.log
522* and is useful for providing formatting to debugging.
523*
524*/ Example Use:
525
526 TraceNL();
527 Prints a carriage return to allegro.log.
528
529/************************************************************************************************************/
530
531void TraceS(int s[]); ZASM Instruction:
532 TRACE6 d3
533/**
534* Works as Trace() above, but prints a full string to allegro.log, using the array pointer
535* (name) as its argument.
536* Maximum 512 characters. Functions from string.zh can be used to split larger strings.
537*
538*/ Example Use:
539
540 int testString[]="This is a string.";
541 TraceS(testString);
542 Prints 'This is a string.' to allegro.log.
543
544/************************************************************************************************************/
545
546///////////////////////
547/// Array Functions ///
548///////////////////////
549
550
551int SizeOfArray(int array[]); ZASM Instruction:
552 ARRAYSIZE d2
553/**
554* Returns the index size of the array pointed by 'array'.
555* Works only on int, and float type arrays. Boolean arrays are not supported.
556* Useful in for loops.
557*
558*/ Example Use:
559
560 int isAnArray[216];
561 int x;
562 x = SizeOfArray(isAnArray);
563 The value of x becomes 216.
564
565/************************************************************************************************************/
566
567//////////////////////////////
568/// Mathematical Functions ///
569//////////////////////////////
570
571int Rand(int n); ZASM Instruction:
572 RNDR<><> d2,d3
573 RNDV<><>
574
575/**
576* Computes and returns a random integer from 0 to n-1,
577* or a negative value between n+1 and 0 if 'n' is negative.
578*
579* Note: The paramater 'n' is an integer, and any floating point (ZScript float)
580* value passed to it will be truncated (floored) to the nearest integer.
581* Rand(3.75) is identical to Rand(3).
582*/ Example Use:
583
584 Rand(40);
585 Produces a random number between 0 and 39.
586 Rand(-20);
587 produces a random number between -19 and 0.
588
589
590/************************************************************************************************************/
591
592float Sin(float deg); ZASM Instruction:
593 SINR<><> d2,d3
594 SINV<><>
595
596/**
597* Returns the trigonometric sine of the parameter, which is interpreted
598* as a degree value.
599*
600*/ Example Use:
601
602 float x = Sin(32);
603 x = 0.5299
604
605/************************************************************************************************************/
606
607float Cos(float deg); ZASM Instruction:
608 COSR<><> d2,d3
609 COSV<><>
610
611/**
612* Returns the trigonometric cosine of the parameter, which is
613* interpreted as a degree value.
614*
615*/ Example Usage:
616
617 float x = Cos(40);
618 x = 0.7660
619
620/************************************************************************************************************/
621
622float Tan(float deg); ZASM Instruction:
623 TANR<><> d2,d3
624 TANV<><>
625
626/**
627* Returns the trigonometric tangent of the parameter, which is
628* interpreted as a degree value. The return value is undefined if
629* deg is of the form 90 + 180n for an integral value of n.
630*
631*/ Example Use:
632
633 float x = Tan(100);
634 x = -5.6712
635
636/************************************************************************************************************/
637
638//!Sources: OMultImmediate, OArcSinRegister
639//Is there a direct ZASM instruction equivalent, or does this function run as a routine?
640
641float RadianSin(float rad);
642/**
643* Returns the trigonometric sine of the parameter, which is interpreted
644* as a radian value.
645*
646*/ Example Use:
647
648/************************************************************************************************************/
649
650//!Sources: OMultImmediate, OCosRegister
651//Is there a direct ZASM instruction equivalent, or does this function run as a routine?
652
653float RadianCos(float rad);
654/**
655* Returns the trigonometric cosine of the parameter, which is
656* interpreted as a radian value.
657*
658*/ Example Use:
659
660/************************************************************************************************************/
661
662//!Sources: OMultImmediate, OTanRegister
663//Is there a direct ZASM instruction equivalent, or does this function run as a routine?
664
665float RadianTan(float rad);
666/**
667* Returns the trigonometric tangent of the parameter, which is
668* interpreted as a radian value. The return value is undefined for
669* values of rad near (pi/2) + n*pi, for n an integer.
670*
671*/ Example Use:
672
673/************************************************************************************************************/
674
675float ArcTan(int x, int y); ZASM Instruction:
676 ARCTANR<>
677 (Does ARCTANV exist?)
678/**
679* Returns the trigonometric arctangent of the coordinates, which is
680* interpreted as a radian value.
681*
682*/ Example Use:
683
684/************************************************************************************************************/
685
686float ArcSin(float x); ZASM Instruction:
687 ARCSINR<><>
688 ARCSINV<><> (Can't find this in the source code)
689 ffasm.cpp line 217
690/**
691* Returns the trigonometric arcsine of x, which is
692* interpreted as a radian value.
693*
694*/ Example Use:
695
696/************************************************************************************************************/
697
698float ArcCos(float x); ZASM Instruction:
699 ARCCOSR<><>
700 ARCCOSV<><>
701
702/**
703* Returns the trigonometric arccosine of x, which is
704* interpreted as a radian value.
705*
706*/ Example Use:
707
708/************************************************************************************************************/
709
710float Max(float a, float b); ZASM Instruction:
711 MAXR<><>
712 MAXV<><>
713/**
714* Returns the greater of a and b.
715*
716*/ Example Use:
717
718/************************************************************************************************************/
719
720float Min(float a, float b); ZASM Instriction:
721 MINR<><>
722 MINV<><>
723/**
724* Returns the lesser of a and b.
725*
726*/ Example Use:
727
728/************************************************************************************************************/
729
730int Pow(int base, int exp); ZASM Instruction:
731 POWERR<><>
732 POWERV<><>
733/**
734* Returns base^exp. The return value is undefined for base=exp=0. Note
735* also negative values of exp may not be useful, as the return value is
736* truncated to the nearest integer.
737*
738*/ Example Use:
739
740/************************************************************************************************************/
741
742int InvPow(int base, int exp); ZASM Instruction:
743 IPOWERR<><>
744 IPOWERV<><>
745/**
746* Returns base^(1/exp). The return value is undefined for exp=0, or
747* if exp is even and base is negative. Note also that negative values
748* of exp may not be useful, as the return value is truncated to the
749* nearest integer.
750*
751*/ Example Use:
752
753/************************************************************************************************************/
754
755float Log10(float val); ZASM Instruction:
756 LOG10<>
757/**
758* Returns the log of val to the base 10. Any value <= 0 will return 0.
759*
760*/ Example Use:
761
762/************************************************************************************************************/
763
764float Ln(float val); ZASM Instruction:
765 LOGE<>
766
767/**
768* Returns the natural logarithm of val (to the base e). Any value <= 0 will return 0.
769*
770*/ Example Use:
771
772/************************************************************************************************************/
773
774int Factorial(int val); ZASM Instruction:
775 FACTORIAL<>
776/**
777* Returns val!. val < 0 returns 0.
778*
779*/ Example Use:
780
781/************************************************************************************************************/
782
783float Abs(float val); ZASM Instruction:
784 ABS<>
785/**
786* Return the absolute value of the parameter, if possible. If the
787* absolute value would overflow the parameter, the return value is
788* undefined.
789*
790*/ Example Use:
791
792/************************************************************************************************************/
793
794float Sqrt(float val); ZASM Instruction:
795 SQROOTV<><>
796 SQROOTR<><>
797/**
798* Computes the square root of the parameter. The return value is
799* undefined for val < 0.
800* NOTE: Passing negative values to Sqrt() will return an error. See SafeSqrt() in std.zh
801*/ Example Use:
802
803 int x = Sqrt(16);
804 x = 4
805
806/************************************************************************************************************/
807/************************************************************************************************************/
808
809
810
811//====================================
812//--- Game Functions and Variables ---
813//====================================
814
815 namespace Game
816
817
818
819 int GetCurScreen(); ZASM Instruction:
820 CURSCR
821 /**
822 * Retrieves the number of the current screen within the current map.
823 */ Example Use: !#!
824
825/************************************************************************************************************/
826
827 int GetCurDMapScreen(); ZASM Instruction:
828 CURDSCR
829 /**
830 * Retrieves the number of the current screen within the current DMap.
831 */ Example Use: !#!
832
833/************************************************************************************************************/
834
835 int GetCurLevel(); ZASM Instruction:
836 CURLEVEL
837 /**
838 * Retrieves the number of the dungeon level of the current DMap. Multiple
839 * DMaps can have the same dungeon level - this signifies that they share
840 * a map, compass, level keys and such.
841 */ Example Use: !#!
842
843/************************************************************************************************************/
844
845 int GetCurMap(); ZASM Instruction:
846 CURMAAP
847 /**
848 * Retrieves the number of the current map.
849 */ Example Use: !#!
850
851/************************************************************************************************************/
852
853 int GetCurDMap(); ZASM Instruction:
854 CURDMAP
855 /**
856 * Returns the number of the current DMap.
857 */ Example Use: !#!
858
859/************************************************************************************************************/
860
861 int DMapFlags[]; ZASM Instruction:
862 DMAPFLAGSD
863 /**
864 * An array of 512 integers, containing the DMap's flags ORed (|) together.
865 * Use the 'DMF_' constants, or the 'DMapFlag()' functions from std.zh if you are not comfortable with binary.
866 */ Example Use: !#!
867
868/************************************************************************************************************/
869
870 int DMapLevel[]; ZASM Instruction:
871 DMAPLEVELD
872 /**
873 * An array of 512 integers containing each DMap's level
874 */ Example Use: !#!
875
876/************************************************************************************************************/
877
878 int DMapCompass[]; ZASM Instruction:
879 DMAPCOMPASSD
880 /**
881 * An array of 512 integers containing each DMap's compass screen
882 */ Example Use: !#!
883
884/************************************************************************************************************/
885
886 int DMapContinue[]; ZASM Instruction:
887 DMAPCONTINUED
888 /**
889 * An array of 512 integers containing each DMap's continue screen
890 */ Example Use: !#!
891
892/************************************************************************************************************/
893
894 int DMapMIDI[]; ZASM Instruction:
895 DMAPMIDID
896 /**
897 * An array of 512 integers containing each DMap's MIDI.
898 * Positive numbers are for custom MIDIs, and negative values are used for
899 * the built-in game MIDIs. Because of the way DMap MIDIs are handled
900 * internally, however, built-in MIDIs besides the overworld, dungeon, and
901 * level 9 songs won't match up with Game->PlayMIDI() and Game->GetMIDI().
902 */ Example Use: !#!
903
904/************************************************************************************************************/
905
906 void GetDMapName(int DMap, int buffer[]);
907
908 ZASM Instruction:
909 GETDMAPNAME
910 /**
911 * Loads DMap with ID 'DMap's name into 'buffer'.
912 * See std_constsnts.zh for appropriate buffer size.
913 */ Example Use: !#!
914
915/************************************************************************************************************/
916
917 void GetDMapTitle(int DMap, int buffer[]);
918
919 ZASM Instruction:
920 GETDMAPTITLE
921 /**
922 * Loads DMap with ID 'DMap's title into 'buffer'.
923 * See std_constants.zh for appropriate buffer size.
924 */ Example Use: !#!
925
926/************************************************************************************************************/
927
928 void GetDMapIntro(int DMap, int buffer[]);
929
930 ZASM Instruction:
931 GETDMAPINTRO
932 /**
933 * Loads DMap with ID 'DMap's intro string into 'buffer'.
934 * See std_constants.zh for appropriate buffer size.
935 */ Example Use: !#!
936
937/************************************************************************************************************/
938
939 int DMapOffset[]; ZASM Instruction:
940 DMAPOFFSET
941 /**
942 * An array of 512 integers containing the X offset of each DMap.
943 * Game->DMapOffset is read-only; while setting it is not syntactically
944 * incorrect, it does nothing.
945 */ Example Use: !#!
946
947/************************************************************************************************************/
948
949 int DMapMap[]; ZASM Instruction:
950 DMAPMAP
951
952 /**
953 * An array of 512 integers containing the map used by each DMap.
954 * Game->DMapMap is read-only; while setting it is not syntactically
955 * incorrect, it does nothing.
956 */ Example Use: !#!
957
958/************************************************************************************************************/
959
960 int NumDeaths; ZASM Instruction:
961 GAMEDEATHS
962 /**
963 * Returns or sets the number of times Link has perished during this quest.
964 */ Example Use: !#!
965
966/************************************************************************************************************/
967
968 int Cheat; ZASM Instruction:
969 GAMECHEAT
970 /**
971 * Returns, or sets the current cheat level of the quest player.
972 * Valid values are 0, 1, 2, 3, and 4.
973 */ Example Use: !#!
974
975/************************************************************************************************************/
976
977 bool CappedFPS; ZASM Instruction:
978 GAMETHROTTLE
979 /**
980 * Returns if the user enabled an uncapped mode either with F1 or TILDE.
981 * Returns 'true' is the game is capped to 60fps, or false otherwise.
982 * At present, you may get (read), but NOT set (write to) this value.
983 */ Example Use: !#!
984
985/************************************************************************************************************/
986
987 int Time ZASM Instruction:
988 GAMETIME
989 /**
990 * Returns the time elapsed in this quest, in 60ths of a second. (i.e. in frames).
991 * The return value is undefined if TimeValid is false (see below).
992 */ Example Use: !#!
993
994/************************************************************************************************************/
995
996 bool TimeValid; ZASM Instruction:
997 GAMETIMEVALID
998 /**
999 * True if the elapsed quest time can be determined for the current quest.
1000 */ Example Use: !#!
1001
1002/************************************************************************************************************/
1003
1004 bool HasPlayed; ZASM Instruction:
1005 GAMEHASPLAYED
1006 /**
1007 * This value is true if the current quest session was loaded from a saved
1008 * game, false if the quest was started fresh.
1009 */ Example Use: !#!
1010
1011/************************************************************************************************************/
1012
1013 bool Standalone; ZASM Instruction:
1014 GAMESTANDALONE
1015 /**
1016 * This value is true if the game is running in standalone mode, false if not.
1017 * Game->Standalone is read-only; while setting it is not syntactically
1018 * incorrect, it does nothing.
1019 *
1020 * Standalone mode is set by command line params when launching ZC.
1021 */ Example Use: !#!
1022
1023/************************************************************************************************************/
1024
1025 int GuyCount[]; ZASM Instruction:
1026 GAMEGUYCOUNT
1027 /**
1028 * The number of NPCs (enemies and guys) on screen i of this map, where
1029 * i is the index used to access this array. This array is exclusively used
1030 * to determine which enemies had previously been killed, and thus won't
1031 * return, when you re-enter a screen.
1032 * Note: This is only a count of the enemies that remain on a screen; not their IDs.
1033 */ Example Use: !#!
1034
1035/************************************************************************************************************/
1036
1037 int ContinueDMap; ZASM Instruction:
1038 GAMECONTDMAP
1039 /**
1040 * Returns or sets the DMap where Link will be respawned after quitting and reloading the game.
1041 */ Example Use: !#!
1042
1043/************************************************************************************************************/
1044
1045 int ContinueScreen; ZASM Instruction:
1046 GAMECONTSCR
1047 /**
1048 * Returns or sets the map screen where Link will be respawned after quitting and reloading the game.
1049 */ Example Use: !#!
1050
1051/************************************************************************************************************/
1052
1053 int LastEntranceDMap; ZASM Instruction:
1054 GAMEENTRDMAP
1055 /**
1056 * Returns or sets the DMap where Link will be respawned after dying and continuing.
1057 */ Example Use: !#!
1058
1059/************************************************************************************************************/
1060
1061 int LastEntranceScreen; ZASM Instruction:
1062 GAMEENTRSCR
1063 /**
1064 * Returns or sets the map screen where Link will be respawned after dying and continuing.
1065 */ Example Use: !#!
1066
1067/************************************************************************************************************/
1068
1069 int Counter[]; ZASM Instruction:
1070 GAMECOUNTERD
1071 /**
1072 * Returns of sets the current value of the game counters.
1073 * Use the CR_ constants in std.zh to index into this array.
1074 */ Example Use: !#!
1075
1076/************************************************************************************************************/
1077
1078 int MCounter[]; ZASM Instruction:
1079 GAMEMCOUNTERD
1080 /**
1081 * Returns or sets the current maximum value of the game counters.
1082 * Use the CR_ constants in std.zh to index into this array.
1083 */ Example Use: !#!
1084
1085/************************************************************************************************************/
1086
1087 int DCounter[]; ZASM Instruction:
1088 GAMEDCOUNTERD
1089 /**
1090 * Returns of sets the current value of the game drain counters.
1091 * Use the CR_ constants in std.zh to index into this array.
1092 * Note that if the player hasn't acquired the '1/2 Magic Upgrade' yet,
1093 * then setting the CR_MAGIC drain counter to a negative value will
1094 * drain the magic counter by 2 per frame rather than 1.
1095 */ Example Use: !#!
1096
1097/************************************************************************************************************/
1098
1099 int Generic[]; ZASM Instruction:
1100 GAMEGENERICD
1101 /**
1102 * An array of miscellaneous game values, such as number of heart
1103 * containers and magic drain rate.
1104 * Use the GEN_ constants in std.zh to index into this array.
1105 */ Example Use: !#!
1106
1107/************************************************************************************************************/
1108
1109 int LItems ZASM Instruction:
1110 GAMELITEMSD
1111 /**
1112 * The exploration items (map, compass, boss key etc.) of dungeon level i
1113 * currently under the possession of the player, where i is
1114 * the index used to access this array. Each element of this
1115 * array consists of flags OR'd (|) together; use the LI_ constants in
1116 * std.zh to set or compare these values.
1117 */ Example Use: !#!
1118
1119/************************************************************************************************************/
1120
1121 int LKeys[]; ZASM Instruction:
1122 GAMELKEYSD
1123 /**
1124 * The number of level keys of level i currently under the possession of
1125 * the player, where i is the index used to access this array.
1126 */ Example Use: !#!
1127
1128/************************************************************************************************************/
1129
1130 int GetScreenFlags(int map, int screen, int flagset);
1131
1132 ZASM Instruction:
1133 GETSCREENFLAGS
1134 /**
1135 * Returns the screen flags from screen 'screen' on map 'map',
1136 * interpreted in the same way as Screen->Flags
1137 */ Example Use: !#!
1138
1139
1140 Game->LKeys[3]+=4; //Gives the player four keys to Level 3.
1141
1142
1143/************************************************************************************************************/
1144
1145 int GetScreenEFlags(int map, int screen, int flagset);
1146
1147 ZASM Instruction:
1148 GETSCREENEFLAGS
1149
1150 /**
1151 * Returns the enemy flags from screen 'screen' on map 'map',
1152 * interpreted in the same way as Screen->EFlags
1153 */ Example Use: !#!
1154
1155/************************************************************************************************************/
1156
1157 bool GetScreenState(int map, int screen, int flag);
1158
1159 ZASM Instruction:
1160 SCREENSTATEDD
1161 /**
1162 * As with State, but retrieves the miscellaneous flags of any screen,
1163 * not just the current one. This function is undefined if map is less
1164 * than 1 or greater than the maximum map number of your quest, or if
1165 * screen is greater than 127.
1166 * Note: Screen numbers in ZQuest are usually displayed in hexadecimal.
1167 * Use the ST_ constants in std.zh for the flag parameter.
1168 */ Example Use: !#!
1169
1170/************************************************************************************************************/
1171
1172 void SetScreenState(int map, int screen, int flag, bool value);
1173
1174 ZASM Instruction:
1175 SCREENSTATEDD
1176
1177 /**
1178 * As with State, but sets the miscellaneous flags of any screen, not
1179 * just the current one. This function is undefined if map is less than
1180 * 1 or greater than the maximum map number of your quest, or if
1181 * screen is greater than 127.
1182 * Note: Screen numbers in ZQuest are usually displayed in hexadecimal.
1183 * Use the ST_ constants in std.zh for the flag parameter.
1184 */ Example Use: !#!
1185
1186/************************************************************************************************************/
1187
1188 float GetScreenD(int screen, int reg);
1189
1190 ZASM Instruction:
1191 SDDD
1192 /**
1193 * Retrieves the value of D[reg] on the given screen of the current
1194 * DMap.
1195 */ Example Use: !#!
1196
1197/************************************************************************************************************/
1198
1199 void SetScreenD(int screen, int reg, float value);
1200
1201 ZASM Instruction:
1202 SDDD
1203 /**
1204 * Sets the value of D[reg] on the given screen of the current DMap.
1205 */ Example Use: !#!
1206
1207/************************************************************************************************************/
1208
1209 float GetDMapScreenD(int dmap, int screen, int reg);
1210
1211 ZASM Instruction:
1212 SDDDD
1213 /**
1214 * Retrieves the value of D[reg] on the given screen of the given
1215 * DMap.
1216 */ Example Use: !#!
1217
1218/************************************************************************************************************/
1219
1220 void SetDMapScreenD(int dmap, int screen, int reg, float value
1221
1222 ZASM Instruction:
1223 SDDDD
1224 /**
1225 * Sets the value of D[reg] on the given screen of the given DMap.
1226 */ Example Use: !#!
1227
1228 itemdata LoadItemData(int item);
1229 LOADITEMDATAR
1230 LOADITEMDATAV
1231 /**
1232 * Retrieves the itemdata pointer corresponding to the given item.
1233 * Use the item pointer ID variable or I_ constants in std.zh as values.
1234 */ Example Use: !#!
1235 Game->LoadItemData[I_BRANG1]
1236
1237
1238/************************************************************************************************************/
1239 //! This compiles, but it is incomplete and returns 0.
1240 float GetDMapScreenDoor(int dmap, int screen, int door);
1241
1242 ZASM Instruction:
1243 n/a
1244 /**
1245 * Retrieves the value of Screen->Door[door] on the given screen of the given
1246 * DMap.
1247 */ Example Use: !#!
1248
1249/************************************************************************************************************/
1250 //! This compiles, but it is incomplete and returns 0.
1251 void SetDMapScreenDoor(int dmap, int screen, int door, float value
1252
1253 ZASM Instruction:
1254 SDDDD
1255 /**
1256 * Sets the value of Screen->Door[door] on the given screen of the given DMap.
1257 */ Example Use: !#!
1258
1259
1260/************************************************************************************************************/
1261 //! This compiles, but it is incomplete and returns 0.
1262 bool GetDMapScreenState(int dmap, int screen, int index);
1263
1264 ZASM Instruction:
1265 n/a
1266 /**
1267 * Retrieves the value of Screen->State[index] on the given screen of the given
1268 * DMap.
1269 */ Example Use: !#!
1270
1271/************************************************************************************************************/
1272 //! This compiles, but it is incomplete and returns 0.
1273 void SetDMapScreenState(int dmap, int screen, int index, bool value
1274
1275 ZASM Instruction:
1276 SDDDD
1277 /**
1278 * Sets the value of Screen->State[index] on the given screen of the given DMap.
1279 */ Example Use: !#!
1280
1281
1282/************************************************************************************************************/
1283
1284 void PlaySound(int soundid); ZASM Instruction:
1285 PLAYSOUNDR
1286 PLAYSOUNDV
1287 /**
1288 * Plays one of the quest's sound effects. Use the SFX_ constants in
1289 * std.zh as values of soundid.
1290 */ Example Use: !#!
1291
1292/************************************************************************************************************/
1293
1294 void PlayMIDI(int MIDIid); ZASM Instruction:
1295 PLAYMIDIR
1296 PLAYMIDIV
1297 /**
1298 * Changes the current screen MIDI to MIDIid.
1299 * Will revert to the DMap (or screen) MIDI upon leaving the screen.
1300 */ Example Use: !#!
1301
1302/************************************************************************************************************/
1303
1304 int GetMIDI(); ZASM Instruction:
1305 GETMIDI
1306 /**
1307 * Returns the current screen MIDI that is playing.
1308 * Positive numbers are for custom MIDIs, and negative values are used
1309 * for the built-in game MIDIs.
1310 */ Example Use: !#!
1311
1312/************************************************************************************************************/
1313
1314 bool PlayEnhancedMusic(int filename[], int track);
1315
1316 ZASM Instruction:
1317 PLAYENHMUSIC
1318 /**
1319 * Play the specified enhanced music if it's available. If the music
1320 * cannot be played, the current music will continue. The music will
1321 * revert to normal upon leaving the screen.
1322 * Returns true if the music file was loaded successfully.
1323 * The filename cannot be more than 255 characters. If the music format
1324 * does not support multiple tracks, the track argument will be ignored.
1325 */ Example Use:
1326
1327 int music[]="myfile.mp3"; // Make a string with the filename of the music to play.
1328 if ( !Game->PlayEnhancedMusic(music, 1) ) Game->PlayMIDI(midi_id);
1329
1330 // Plays the enhanced music file 'myfle.mp3', track 1.
1331 // If the file is mssing, the game will instead play
1332 // the midi specified as midi_id.
1333
1334/************************************************************************************************************/
1335
1336 void GetDMapMusicFilename(int dmap, int buf[]);
1337
1338 ZASM Instruction:
1339 GETMUSICFILE
1340 /**
1341 * Load the filename of the given DMap's enhanced music into buf.
1342 * buf should be at least 256 elements in size.
1343 */ Example Use: !#!
1344
1345/************************************************************************************************************/
1346
1347 int GetDMapMusicTrack(int dmap);
1348
1349 ZASM Instruction:
1350 GETMUSICTRACK
1351 /**
1352 * Returns the given DMap's enhanced music track. This is valid but
1353 * meaningless if the music format doesn't support multiple tracks.
1354 */ Example Use: !#!
1355
1356/************************************************************************************************************/
1357
1358 void SetDMapEnhancedMusic(int dmap, int filename[], int track);
1359
1360 ZASM Instruction:
1361 SETDMAPENHMUSIC
1362 /**
1363 * Sets the specified DMap's enhanced music to the given filename and
1364 * track number. If the music format does not support multiple tracks,
1365 * the track argument will be ignored. The filename must not be more
1366 * than 255 characters.
1367 */ Example Use: !#!
1368
1369/************************************************************************************************************/
1370
1371 int GetComboData(int map, int screen, int position);
1372
1373 ZASM Instruction:
1374 COMBODDM
1375 /**
1376 * Grabs a particular combo reference from anywhere in the game
1377 * world, based on map (NOT DMap), screen number, and position.
1378 * Don't forget that the screen index should be in hexadecimal,
1379 * and that maps are counted from 1 upwards.
1380 * Position is considered an index, treated the same way as in
1381 * Screen->ComboD[], with a legal range of 0 to 175.
1382 */ Example Use: !#!
1383
1384/************************************************************************************************************/
1385
1386 void SetComboData(int map, int screen, int position, int value);
1387
1388 ZASM Instruction:
1389 COMBODDM
1390 /**
1391 * Sets a particular combo reference anywhere in the game world,
1392 * based on map (NOT DMap), screen number, and position.
1393 * Don't forget that the screen index should be in hexadecimal,
1394 * and that maps are counted from 1 upwards.
1395 * Position is considered an index, treated the same way as in
1396 * Screen->ComboD[], with a legal range of 0 to 175.
1397 */ Example Use: !#!
1398
1399/************************************************************************************************************/
1400
1401 int GetComboCSet(int map, int screen, int position);
1402
1403 ZASM Instruction:
1404 COMBOCDM
1405 /**
1406 * Grabs a particular combo's CSet from anywhere in the game
1407 * world, based on map (NOT DMap), screen number, and position.
1408 * Position is considered an index, treated the same way as in
1409 * Screen->ComboC[], with a legal range of 0 to 175.
1410 */ Example Use: !#!
1411
1412/************************************************************************************************************/
1413
1414 void SetComboCSet(int map, int screen, int position, int value);
1415
1416 ZASM Instruction:
1417 COMBOCDM
1418 /**
1419 * Sets a particular combo's CSet anywhere in the game world,
1420 * based on map (NOT DMap), screen number, and position. Position
1421 * is considered an index, treated the same way as in Screen->ComboC[]
1422 * with a legal range of 0 to 175.
1423 */ Example Use: !#!
1424
1425/************************************************************************************************************/
1426
1427 int GetComboFlag(int map, int screen, int position);
1428
1429 ZASM Instruction:
1430 COMBOFDM
1431 /**
1432 * Grabs a particular combo's placed flag from anywhere in the game
1433 * world, based on map (NOT DMap), screen number, and position.
1434 * Position is considered an index, treated the same way as in
1435 * Screen->ComboF[], with a legal range of 0 to 175.
1436 */ Example Use: !#!
1437
1438/************************************************************************************************************/
1439
1440 void SetComboFlag(int map, int screen, int position, int value);
1441
1442 ZASM Instruction:
1443 COMBOFDM
1444 /**
1445 * Sets a particular combo's placed flag anywhere in the game world,
1446 * based on map (NOT DMap), screen number, and position. Position
1447 * is considered an index, treated the same way as in Screen->ComboF[]
1448 * with a legal range of 0 to 175.
1449 */ Example Use: !#!
1450
1451/************************************************************************************************************/
1452
1453 int GetComboType(int map, int screen, int position);
1454
1455 ZASM Instruction:
1456 COMBOTDM
1457 /**
1458 * Grabs a particular combo's type from anywhere in the game
1459 * world, based on map (NOT DMap), screen number, and position.
1460 * Position is considered an index, treated the same way as in
1461 * Screen->ComboT[]. Note that you are grabbing an actual combo
1462 * attribute as referenced by the combo on screen you're
1463 * referring to.
1464 */ Example Use: !#!
1465
1466/************************************************************************************************************/
1467
1468 void SetComboType(int map, int screen, int position, int value);
1469
1470 ZASM Instruction:
1471 COMBOTDM
1472 /**
1473 * Sets a particular combo's type anywhere in the game world,
1474 * based on map (NOT DMap), screen number, and position. Position
1475 * is considered an index, treated the same way as in Screen->ComboT[].
1476 * Note that you are grabbing an actual combo attribute as referenced
1477 * by the combo on screen you're referring to, which means that
1478 * setting this attribute will affect ALL references to this combo
1479 * throughout the quest.
1480 */ Example Use: !#!
1481
1482/************************************************************************************************************/
1483
1484 int GetComboInherentFlag(int map, int screen, int position);
1485
1486 ZASM Instruction:
1487 COMBOIDM
1488 /**
1489 * Grabs a particular combo's inherent flag from anywhere in the game
1490 * world, based on map (NOT DMap), screen number, and position.
1491 * Position is considered an index, treated the same way as in
1492 * Screen->ComboI[]. Note that you are grabbing an actual combo
1493 * attribute as referenced by the combo on screen you're
1494 * referring to.
1495 */ Example Use: !#!
1496
1497/************************************************************************************************************/
1498
1499 void SetComboInherentFlag(int map, int screen, int position, int value);
1500
1501 ZASM Instruction:
1502 COMBOIDM
1503 /**
1504 * Sets a particular combo's inherent flag anywhere in the game world,
1505 * based on map (NOT DMap), screen number, and position. Position
1506 * is considered an index, treated the same way as in Screen->ComboI[].
1507 * Note that you are grabbing an actual combo attribute as referenced
1508 * by the combo on screen you're referring to, which means that
1509 * setting this attribute will affect ALL references to this combo
1510 * throughout the quest.
1511 */ Example Use: !#!
1512
1513/************************************************************************************************************/
1514
1515 int GetComboSolid(int map, int screen, int position);
1516
1517 ZASM Instruction:
1518 COMBOSDM
1519 /**
1520 * Grabs a particular combo's solidity flag from anywhere in the game
1521 * world, based on map (NOT DMap), screen number, and position.
1522 * Position is considered an index, treated the same way as in
1523 * Screen->ComboS[]. Note that you are grabbing an actual combo
1524 * attribute as referenced by the combo on screen you're
1525 * referring to.
1526 */ Example Use: !#!
1527
1528/************************************************************************************************************/
1529
1530 void SetComboSolid(int map, int screen, int position, int value);
1531
1532 ZASM Instruction:
1533 COMBOSDM
1534 /**
1535 * Sets a particular combo's solidity anywhere in the game world,
1536 * based on map (NOT DMap), screen number, and position. Position
1537 * is considered an index, treated the same way as in Screen->ComboS[].
1538 * Note that you are grabbing an actual combo attribute as referenced
1539 * by the combo on screen you're referring to, which means that
1540 * setting this attribute will affect ALL references to this combo
1541 * throughout the quest.
1542 */ Example Use: !#!
1543
1544/************************************************************************************************************/
1545
1546 int ComboTile(int combo); ZASM Instruction:
1547 COMBOTILE
1548 /**
1549 * Returns the tile used by combo 'combo'
1550 */ Example Use: !#!
1551
1552/************************************************************************************************************/
1553
1554 void GetSaveName(int buffer[]);
1555
1556 ZASM Instruction:
1557 GETSAVENAME
1558 /**
1559 * Loads the current save file's name into 'buffer'
1560 * Buffer should be at least 9 elements long
1561 */ Example Use: !#!
1562
1563/************************************************************************************************************/
1564
1565 void SetSaveName(int name[]);
1566
1567 ZASM Instruction:
1568 SETSAVENAME
1569 /**
1570 * Sets the current file's save name to 'name'
1571 * Buffer should be no more than 9 elements
1572 */ Example Use: !#!
1573
1574/************************************************************************************************************/
1575
1576 void End(); ZASM Instruction:
1577 GAMEEND
1578 /**
1579 * IMMEDIATELY ends the current game and returns to the file select screen
1580 */ Example Use: !#!
1581
1582/************************************************************************************************************/
1583
1584 void Save(); ZASM Instruction:
1585 GAMESAVE
1586 /**
1587 * Saves the current game
1588 */ Example Use: !#!
1589
1590/************************************************************************************************************/
1591
1592 bool ShowSaveScreen(); ZASM Instruction:
1593 SAVESCREEN
1594 /**
1595 * Displays the save screen. Returns true if the user chose to save, false otherwise.
1596 */ Example Use: !#!
1597
1598/************************************************************************************************************/
1599
1600 void ShowSaveQuitScreen(); ZASM Instruction:
1601 SAVEQUITSCREEN
1602 /**
1603 * Displays the save and quit screen.
1604 */ Example Use: !#!
1605
1606/************************************************************************************************************/
1607
1608 void GetMessage(int string, int buffer[]);
1609
1610 ZASM Instruction:
1611 GETMESSAGE
1612 /**
1613 * Loads 'string' into 'buffer'. Use the function from std.zh
1614 * or use string.zh to remove trailing ' ' characters whilst loading.
1615 */ Example Use: !#!
1616
1617/************************************************************************************************************/
1618
1619 int GetFFCScript(int name[]); ZASM Instruction:
1620 GETFFCSCRIPT
1621 /**
1622 * Returns the number of the script with the given name or -1 if there is
1623 * no such script. The script name should be passed as a string.
1624 * (!) This was added around 2.50.0 RC4. Earlier beta versions will not be able to perform this function.
1625 */ Example Use: !#!
1626
1627/************************************************************************************************************/
1628
1629 bool ClickToFreezeEnabled; ZASM Instruction:
1630 GAMECLICKFREEZE
1631 /**
1632 * If this is false, the "Click to Freeze" setting will not function, ensuring
1633 * that the script can use the mouse freely. This overrides the setting rather
1634 * than changing it, so remembering and restoring the initial value is unnecessary.
1635 */ Example Use: !#!
1636
1637/************************************************************************************************************/
1638/************************************************************************************************************/
1639
1640//======================================
1641//--- Screen Functions and Variables ---
1642//======================================
1643
1644 namespace Screen
1645
1646float D[]; ZASM Instruction:
1647 SD
1648 SDD
1649
1650
1651/**
1652* Each screen has 8 general purpose registers for use by script
1653* programmers. These values are recorded in the save file when the
1654* player saves their game. Do with these as you will.
1655* Note that these registers are tied to screen/DMap combinations.
1656* Encountering the same screen in a different DMap will result in a
1657* different D[] array.
1658*
1659* Values in Screen->D are preserved through game saving.
1660*
1661*/ Example Use: !#!
1662
1663/************************************************************************************************************/
1664
1665int Flags[]; ZASM Instruction:
1666 SCREENFLAGSD
1667 SCREENFLAGS
1668
1669/**
1670* An array of ten integers containing the states of the flags in the
1671* 10 categories on the Screen Data tabs 1 and 2. Each flag is ORed into the
1672* Flags[x] value, starting with the top flag as the smallest bit.
1673* Use the SF_ constants as the array acces for this value, and the
1674* GetScreenFlags function if you are not comfortable with binary.
1675* This is read-only; while setting it is not syntactically incorrect, it does nothing.
1676*
1677*/ Example Use: !#!
1678
1679/************************************************************************************************************/
1680
1681int EFlags[]; ZASM Instruction:
1682 SCREENEFLAGSD
1683 SCREENEFLAGS
1684
1685/**
1686* An array of 3 integers containing the states of the flags in the
1687* E.Flags tab of the Screen Data dialog. Each flag is ORed into the
1688* EFlags[x] value, starting with the top flag as the smallest bit.
1689* Use the SEF_ constants as the array acces for this value, and the
1690* GetScreenEFlags function if you are not comfortable with binary.
1691* This is read-only; while setting it is not syntactically incorrect, it does nothing.
1692*
1693*/ Example Use: !#!
1694
1695/************************************************************************************************************/
1696
1697int ComboD[]; ZASM Instruction:
1698 CD### COMBOD
1699 COMBODD COMBODDM
1700 COMBODDM COMBOSD
1701
1702/**
1703* The combo ID of the ith combo on the screen, where i is the index
1704* used to access this array. Combos are counted left to right, top to
1705* bottom.
1706* Screen dimensions are 16 combos wide, by 11 combos high.
1707*
1708*/ Example Use: !#!
1709
1710/************************************************************************************************************/
1711
1712int ComboC[]; ZASM Instruction:
1713 CC### COMBOC
1714 COMBOCD COMBOCDM
1715
1716/**
1717* The CSet of the tile used by the ith combo on the screen, where i is
1718* the index used to access this array. Combos are counted left to right,
1719* top to bottom.
1720* Screen dimensions are 16 combos wide, by 11 combos high.
1721*
1722*/ Example Use: !#!
1723
1724/************************************************************************************************************/
1725
1726int ComboF[]; ZASM Instruction:
1727 CF### COMBOF
1728 COMBOFD COMBOFDM
1729
1730/**
1731* The placed flag of the ith combo on the screen, where i is the index
1732* used to access this array. Combos are counted left to right, top to
1733* bottom. Use the CF_ constants in std.zh to set or compare these values.
1734* Screen dimensions are 16 combos wide, by 11 combos high.
1735*
1736*/ Example Use: !#!
1737
1738/************************************************************************************************************/
1739
1740int ComboI[]; ZASM Instruction:
1741 CI### COMBOID
1742 COMBOIDM
1743
1744
1745/**
1746* The inherent flag of the ith combo on the screen, where i is the index
1747* used to access this array. Combos are counted left to right, top to
1748* bottom. Use the CF_ constants in std.zh to set or compare these values.
1749* Screen dimensions are 16 combos wide, by 11 combos high.
1750*
1751*/ Example Use: !#!
1752
1753/************************************************************************************************************/
1754
1755int ComboT[]; ZASM Instruction:
1756 CT### COMBOTD
1757 COMBOTDM
1758
1759
1760/**
1761* The combo type of the ith combo on the screen, where i is the index
1762* used to access this array. Combos are counted left to right, top to
1763* bottom. Use the CT_ constants in std.zh to set or compare these values.
1764* Screen dimensions are 16 combos wide, by 11 combos high.
1765*
1766*/ Example Use: !#!
1767
1768/************************************************************************************************************/
1769
1770int ComboS[]; ZASM Instruction:
1771 CS### COMBOSD
1772 COMBOSDM
1773
1774
1775/**
1776* The walkability mask of the ith combo on the screen, where i is the
1777* index used to access this array. Combos are counted left to right, top
1778* to bottom. The least signficant bit is true if the top-left of the combo
1779* is solid, the second-least signficant bit is true if the bottom-left
1780* of the combo is is solid, the third-least significant bit is true if the
1781* top-right of the combo is solid, and the fourth-least significant bit is
1782* true if the bottom-right of the combo is solid.
1783* Screen dimensions are 16 combos wide, by 11 combos high.
1784*
1785*/ Example Use: !#!
1786
1787/************************************************************************************************************/
1788
1789int MovingBlockX; ZASM Instruction:
1790 PUSHBLOCKX
1791
1792
1793/**
1794* The X position of the current moving block. If there is no moving block
1795* on the screen, it will be -1. This is read-only; while setting it is not
1796* syntactically incorrect, it does nothing.
1797*
1798*/ Example Use: !#!
1799
1800/************************************************************************************************************/
1801
1802int MovingBlockY; ZASM Instruction:
1803 PUSHBLOCKY
1804
1805/**
1806* The Y position of the current moving block. If there is no moving block
1807* on the screen, it will be -1. This is read-only; while setting it is not
1808* syntactically incorrect, it does nothing.
1809*
1810*/ Example Use: !#!
1811
1812/************************************************************************************************************/
1813
1814int MovingBlockCombo; ZASM Instruction:
1815 PUSHBLOCKCOMBO
1816
1817/**
1818* The combo used by moving block. If there is no block moving, the value
1819* is undefined.
1820*
1821*/ Example Use: !#!
1822
1823/************************************************************************************************************/
1824
1825int MovingBlockCSet; ZASM Instruction:
1826 PUSHBLOCKCSET
1827
1828/**
1829* The CSet used by moving block. If there is no block moving, the value
1830* is undefined.
1831*
1832*/ Example Use: !#!
1833
1834/************************************************************************************************************/
1835
1836int UnderCombo; ZASM Instruction:
1837 UNDERCOMBO
1838
1839/**
1840* The current screen's under combo.
1841* !#! Is setting this legal?
1842*
1843*/ Example Use: !#!
1844
1845/************************************************************************************************************/
1846
1847int UnderCSet; ZASM Instruction:
1848 UNDERCSET
1849
1850/**
1851* The current screen's under CSet.
1852* !#! Is setting this legal?
1853*
1854*/ Example Use: !#!
1855
1856/************************************************************************************************************/
1857
1858bool State[]; ZASM Instruction:
1859 SCREENSTATED
1860
1861/**
1862* An array of miscellaneous status data associated with the current
1863* screen.
1864* Screen states involve such things as permanent screen secrets, the
1865* status of lock blocks and treasure chest combos, and whether items have
1866* been collected.
1867* These values are recorded in the save file when the player saves their
1868* game. Use the ST_ constants in std.zh as indices into this array.
1869*
1870*/ Example Use: !#!
1871
1872/************************************************************************************************************/
1873
1874int Door[]; ZASM Instruction:
1875 SCRDOORD
1876 SCRDOOR
1877
1878/**
1879* The door type for each of the four doors on a screen. Doors are counted
1880* using the first four DIR_ constants in std.zh. Use the D_ constants in
1881* std.zh to compare these values.
1882*
1883*/ Example Use: !#!
1884
1885/************************************************************************************************************/
1886
1887int RoomType; ZASM Instruction:
1888 ROOMTYPE
1889
1890/**
1891* The type of room this screen is (Special Item, Bomb Upgrade, etc)
1892* This is currently read-only.
1893* Use the RT_* constants in std.zh
1894*
1895*/ Example Use: !#!
1896
1897/************************************************************************************************************/
1898
1899int RoomData; ZASM Instruction:
1900 ROOMDATA
1901
1902/**
1903* This is the data associated with the room type above. What it means depends
1904* on the room type. For Special Item, it will be the item ID, for a Shop, it
1905* will be the Shop Number, etc.
1906* Basically, this is what's in the "Catch-all" menu item underneath Room Type.
1907* If the room type has no data (eg, Ganon's room), this will be undefined.
1908*
1909*/ Example Use: !#!
1910
1911/************************************************************************************************************/
1912
1913void TriggerSecrets(); ZASM Instruction:
1914 SECRETS ? !#!
1915
1916/**
1917* Triggers screen secrets temporarily. Set Screen->State[ST_SECRET]
1918* to true beforehand or afterward if you would like them to remain
1919* permanent.
1920*
1921*/ Example Use: Screen->TriggerSecrets();
1922
1923
1924/************************************************************************************************************/
1925
1926void WavyIn(); ZASM Instruction:
1927 WAVYIN
1928
1929/**
1930* Replicates the warping screen wave effect (inbound) from a tile warp.
1931*
1932*/ Example Use: !#!
1933
1934/************************************************************************************************************/
1935
1936void WavyOut(); ZASM Instruction:
1937 WAVYOUT
1938
1939/**
1940* Replicates the warping screen wave effect (outbound) from a tile warp.
1941*
1942*/ Example Use: !#!
1943
1944/************************************************************************************************************/
1945
1946void ZapIn(); ZASM Instruction:
1947 ZAPIN
1948
1949/**
1950* Replicates the warping screen zap effect (inbound) from a tile warp.
1951*
1952*/ Example Use: !#!
1953
1954/************************************************************************************************************/
1955
1956void ZapOut(); ZASM Instruction:
1957 ZAPOUT
1958
1959/**
1960* Replicates the warping screen zap effect (outbound) from a tile warp.
1961*
1962*/ Example Use: !#!
1963
1964/************************************************************************************************************/
1965
1966void OpeningWipe(); ZASM Instruction:
1967 OPENWIPE
1968
1969/**
1970* Replicates the opening wipe screen effect (using the quest rule for its type) from a tile warp.
1971*
1972*/ Example Use: !#!
1973
1974/************************************************************************************************************/
1975
1976bool Lit; ZASM Instruction:
1977 LIT
1978
1979/**
1980* Whether or not the screen is lit. Setting this variable will change the
1981* lighting setting of the screen until you change screens.
1982*
1983*/ Example Use: !#!
1984
1985
1986/************************************************************************************************************/
1987
1988int Wavy; ZASM Instruction:
1989 WAVY
1990
1991/**
1992* The time, in frames, that the 'wave' screen effect will be in effect.
1993* This value is decremented once per frame. As the value of Wavy approaches 0,
1994* the intensity of the waves decreases.
1995*
1996*/ Example Use: !#!
1997
1998/************************************************************************************************************/
1999
2000int Quake; ZASM Instruction:
2001 QUAKE
2002
2003/**
2004* The time, in frames, that the screen will shake. This value is decremented
2005* once per frame. As the value of Quake approaches 0, the intensity of the
2006* screen shaking decreases.
2007*
2008*/ Example Use: !#!
2009
2010/************************************************************************************************************/
2011
2012void SetSideWarp(int warp, int screen, int dmap, int type); ZASM Instruction:
2013 SETSIDEWARP
2014
2015/**
2016* Sets the current screen's side warp 'warp' to the destination screen,
2017* DMap and type. If any of the parameters screen, dmap or type are equal
2018* to -1, they will remain unchanged. If warp is not between 0 and 3, the
2019* function does nothing.
2020
2021* Directions match DIR_* in std_constants.zh
2022* Use constants SIDEWARP_* in std_constants.zh
2023*
2024*/ Example Use: !#!
2025
2026/************************************************************************************************************/
2027
2028void SetTileWarp(int warp, int screen, int dmap, int type); ZASM Instruction:
2029 SETTILEWARP
2030
2031/**
2032* Sets the current screen's tile warp 'warp' to the destination screen,
2033* DMap and type. If any of the parameters screen, dmap or type are equal
2034* to -1, they will remain unchanged. If warp is not between 0 and 3, the
2035* function does nothing
2036*
2037* Warp-Tiles A, B, C, and D are 0, 1, 2, and 3 respectively.
2038* Use constants TILEWARP_* in std_constants.zh
2039*
2040*/ Example Use: !#!
2041
2042/************************************************************************************************************/
2043
2044int GetSideWarpDMap(int warp); ZASM Instruction:
2045 GETSIDEWARPDMAP
2046
2047/**
2048* Returns the destination DMap of the given side warp on the current screen.
2049* Returns -1 if warp is not between 0 and 3.
2050*
2051* Side-Warp Directions match DIR_* in std_constants.zh
2052* Use constants SIDEWARP_* in std_constants.zh
2053*
2054*/ Example Use: !#!
2055
2056/************************************************************************************************************/
2057
2058int GetSideWarpScreen(int warp); ZASM Instruction:
2059 GETSIDEWARPSCR
2060
2061/**
2062* Returns the destination screen of the given side warp on the current
2063* screen. Returns -1 if warp is not between 0 and 3.
2064*
2065* Directions match DIR_* in std_constants.zh
2066* Use constants SIDEWARP_* in std_constants.zh
2067*
2068*/ Example Use: !#!
2069
2070/************************************************************************************************************/
2071
2072int GetSideWarpType(int warp); ZASM Instruction:
2073 GETSIDEWARPTYPE
2074
2075/**
2076* Returns the warp type of the given side warp on the current screen.
2077* Returns -1 if warp is not between 0 and 3.
2078*
2079* Directions match DIR_* in std_constants.zh
2080* Use constants SIDEWARP_* in std_constants.zh
2081*
2082*/ Example Use: !#!
2083
2084/************************************************************************************************************/
2085
2086int GetTileWarpDMap(int warp); ZASM Instruction:
2087 GETTILEWARPDMAP
2088
2089/**
2090* Returns the destination DMap of the given tile warp on the current screen.
2091* Returns -1 if warp is not between 0 and 3.
2092*
2093* Warp-Tiles A, B, C, and D are 0, 1, 2, and 3 respectively.
2094* Use constants TILEWARP_* in std_constants.zh
2095*
2096*/ Example Use: !#!
2097
2098/************************************************************************************************************/
2099
2100int GetTileWarpScreen(int warp); ZASM Instruction:
2101 GETTILEWARPSCR
2102
2103/**
2104* Returns the destination screen of the given tile warp on the current
2105* screen. Returns -1 if warp is not between 0 and 3.
2106*
2107* Warp-Tiles A, B, C, and D are 0, 1, 2, and 3 respectively.
2108* Use constants TILEWARP_* in std_constants.zh
2109*
2110*/ Example Use: !#!
2111
2112/************************************************************************************************************/
2113
2114int GetTileWarpType(int warp); ZASM Instruction:
2115 GETTILEWARPTYPE
2116
2117/**
2118* Returns the warp type of the given tile warp on the current screen.
2119* Returns -1 if warp is not between 0 and 3.
2120*
2121* Warp-Tiles A, B, C, and D are 0, 1, 2, and 3 respectively.
2122* Use constants TILEWARP_* in std_constants.zh
2123*
2124*/ Example Use: !#!
2125
2126/************************************************************************************************************/
2127
2128int LayerMap(int n); ZASM Instruction:
2129 LAYERMAP
2130
2131/**
2132* Returns the map of the screen currently being used as the nth layer.
2133* Values of n less than 1 or greater than 6, or layers that are not set up,
2134* returns -1.
2135*
2136*/ Example Use: !#!
2137
2138/************************************************************************************************************/
2139
2140int LayerScreen(int n); ZASM Instruction:
2141 LAYERSCREEN
2142
2143/**
2144* Returns the number of the screen currently being used as the nth layer.
2145* Values of n less than 1 or greater than 6, or layers that are not set up,
2146* returns -1.
2147*
2148*/ Example Use: !#!
2149
2150/************************************************************************************************************/
2151
2152int NumItems(); ZASM Instruction:
2153 ITEMCOUNT
2154
2155/**
2156* Returns the number of items currently present on the screen. Screen
2157* items, shop items, and items dropped by enemies are counted; Link's
2158* weapons, such as lit bombs, or enemy weapons are not counted.
2159* Note that this value is only correct up until the next call to
2160* Waitframe().
2161*
2162*/ Example Use: !#!
2163
2164/************************************************************************************************************/
2165
2166item LoadItem(int num); ZASM Instruction:
2167 LOADITEMR
2168 LOADITEMV
2169
2170/**
2171* Returns a pointer to the numth item on the current screen. The return
2172* value is undefined unless 1 <= num <= NumItems().
2173*
2174* Attempting to return an invalid item pointer will print an error to allegro.log.
2175*
2176*/ Example Use: !#!
2177
2178/************************************************************************************************************/
2179
2180item CreateItem(int id); ZASM Instruction:
2181 CREATEITEMV
2182 CREATEITEMR
2183
2184/**
2185* Returns a pointer to the numth FFC on the current screen. The return
2186* value is undefined unless 1 <= num <= ffcs, where ffcs is the number
2187* of FFCs active on the screen.
2188*
2189*/ Example Use: !#!
2190
2191/************************************************************************************************************/
2192
2193ffc LoadFFC(int num); ZASM Instruction:
2194 GETFFCSCRIPT
2195
2196/**
2197* Returns a pointer to the numth FFC on the current screen. The return
2198* value is undefined unless 1 <= num <= ffcs, where ffcs is the number
2199* of FFCs active on the screen.
2200*
2201*/ Example Use: !#!
2202
2203/************************************************************************************************************/
2204
2205int NumNPCs(); ZASM Instruction:
2206 NPCCOUNT
2207
2208/**
2209* Returns the number of NPCs (enemies and guys) on the screen.
2210* Note that this value is only correct up until the next call to
2211* Waitframe().
2212*
2213*/ Example Use: !#!
2214
2215/************************************************************************************************************/
2216
2217npc LoadNPC(int num); ZASM Instruction:
2218 LOADNPCR
2219 LOADNPCV
2220
2221/**
2222* Returns a pointer to the numth NPC on the current screen. The return
2223* value is undefined unless 1 <= num <= NumNPCs().
2224*
2225*/ Example Use: !#!
2226
2227/************************************************************************************************************/
2228
2229npc CreateNPC(int id); ZASM Instruction:
2230 CREATENPCR
2231 CREATENPCV
2232
2233/**
2234* Creates an npc of the given type at (0,0). Use the NPC_ constants in
2235* std.zh to pass into this method. The return value is a pointer to the
2236* new NPC.
2237* The maximum number of NPCs on any given screen is 255. ZC will report an
2238* error to allegro.log if you try to create NPCs after reaching that maximum.
2239*
2240*/ Example Use: !#!
2241
2242/************************************************************************************************************/
2243
2244int NumLWeapons(); ZASM Instruction:
2245 LWPNCOUNT
2246
2247/**
2248* Returns the number of Link weapon projectiles currently present on the screen.
2249* This includes things like Link's arrows, bombs, magic, etc. Note that this
2250* value is only correct up until the next call of Waitframe().
2251*
2252*/ Example Use: !#!
2253
2254/************************************************************************************************************/
2255
2256lweapon LoadLWeapon(int num); ZASM Instruction:
2257 LOADLWEAPONR
2258 LOADLWEAPONV
2259
2260/**
2261* Returns a pointer to the num-th lweapon on the current screen. The return
2262* value is undefined unless 1 <= num <= NumLWeapons().
2263*
2264*/ Example Use: !#!
2265
2266/************************************************************************************************************/
2267
2268lweapon CreateLWeapon(int type); ZASM Instruction:
2269 CREATELWEAPONR
2270 CREATELWEAPONV
2271
2272/**
2273* Creates an lweapon of the given type at (0,0). Use the LW_ constants in
2274* std.zh to pass into this method. The return value is a pointer to the
2275* new lweapon.
2276* The maximum number of lweapons on any given screen is 255. ZC will NOT report an
2277* error to allegro.log if you try to create lweapons after reaching that maximum.
2278* The maximum instances for lweapons, and eweapons are independent.
2279* This cap is of *all* lweapons, of any type. Mixing types will not increase this cap.
2280*
2281*/ Example Use: !#!
2282
2283/************************************************************************************************************/
2284
2285int NumEWeapons(); ZASM Instruction:
2286 EWPNCOUNT
2287
2288/**
2289* Returns the number of Enemy weapon projectiles currently present on the screen.
2290* This includes things like Enemy arrows, bombs, magic, etc. Note that this
2291* value is only correct up until the next call of Waitframe().
2292*
2293*/ Example Use: !#!
2294
2295/************************************************************************************************************/
2296
2297eweapon LoadEWeapon(int num); ZASM Instruction:
2298 LOADEWEAPONR
2299 LOADEWEAPONV
2300
2301/**
2302* Returns a pointer to the numth eweapon on the current screen. The return
2303* value is undefined unless 1 <= num <= NumEWeapons().
2304*
2305*/ Example Use: !#!
2306
2307/************************************************************************************************************/
2308
2309eweapon CreateEWeapon(int type); ZASM Instruction:
2310 CREATEEWEAPONR
2311 CREATEEWEAPONV
2312
2313/**
2314* Creates an eweapon of the given type at (0,0). Use the EW_ constants in
2315* std.zh to pass into this method. The return value is a pointer to the
2316* new lweapon.
2317* The maximum number of eweapons on any given screen is 255. ZC will NOT report an
2318* error to allegro.log if you try to create eweapons after reaching that maximum.
2319* The maximum instances for eweapons, and lweapons are independent.
2320* This cap is of *all* eweapons, of any type. Mixing types will not increase this cap.
2321*
2322*/ Example Use: !#!
2323
2324/************************************************************************************************************/
2325
2326bool isSolid(int x, int y); ZASM Instruction:
2327 ISSOLID
2328
2329/**
2330* Returns true if the screen position (x, y) is solid - that is, if it
2331* is within the solid portion of a combo on layers 0, 1 or 2. If either
2332* x or y exceed the screen's bounds, then it will return false.
2333* It will also return false if the only applicable solid combo is a solid
2334* water combo that has recently been 'dried' by the whistle.
2335*
2336*/ Example Use: !#!
2337
2338/************************************************************************************************************/
2339
2340void ClearSprites(int spritelist); ZASM Instruction:
2341 CLEARSPRITESR
2342 CLEARSPRITESV
2343
2344/**
2345* Clears all of a certain kind of sprite from the screen. Use the SL_
2346* constants in std.zh to pass into this method.
2347*
2348*/ Example Use: !#!
2349
2350/************************************************************************************************************/
2351
2352void Message(int string);
2353
2354 ZASM Instruction:
2355 MSGSTRR
2356 MSGSTRV
2357/**
2358* Prints the message string with given ID onto the screen.
2359* If string is 0, the currently displayed message is removed.
2360* This method's behavior is undefined if string is less than 0
2361* or greater than the total number of messages in the quest.
2362*/ Example Use: !#!
2363
2364/************************************************************************************************************/
2365
2366 //===============================//
2367 // SCRIPT DRAWING COMMANDS //
2368 //===============================//
2369
2370 /* These commands use the Allegro 4 drawing primitives to render drawn
2371 effects directly to the screen. You may draw to the screen immediately
2372 which is considered RT_SCREEN (see: Render Targets), or you may change
2373 to another render target (1 through 5) and issue your drawing commands,
2374 then render that back to the screen.
2375
2376 All render targets have eight valid layers, 0 through 7.
2377 Drawing colour 0 to a layer of a bitmap render target erases a section of that,
2378 creating a transparent area on that layer. Any transparent area that extends
2379 through all layers will be drawn as transparent when rendered back to the screen
2380 if 'bool mask' is set true.
2381
2382 Drawing colour 0 directly to a screen layer is undefined.
2383
2384 Please note: For all draw primitives, if the quest rule 'Subscreen Appears
2385 Above Sprites' is set,passing the layer argument as 7 will allow drawing
2386 on top of the subscreen.
2387
2388 Tha maximum number of script drawing instructions per frame is 1000.
2389
2390
2391
2392void Rectangle( int layer, int x, int y, int x2, int y2,
2393 int color, float scale,
2394 int rx, int ry, int rangle,
2395 bool fill, int opacity );
2396
2397 ZASM Instruction:
2398 RECTR
2399 RECT
2400
2401/**
2402* Draws a rectangle on the specified layer of the current screen, using args to set its properties:
2403*
2404* METRICS
2405* (x,y) as the top-left corner and (x2,y2) as the bottom-right corner.
2406*
2407* COLOUR
2408*
2409* SCALE AND ROTATION
2410*
2411* FILL AND OPACITY
2412*
2413* Then scales the rectangle uniformly about its center by the given
2414* factor.
2415* Lastly, a rotation, centered about the point (rx, ry), is performed
2416* counterclockwise using an angle of rangle degrees.
2417* A filled rectangle is drawn if fill is true; otherwise, this method
2418* draws a wireframe.
2419* The rectangle is drawn using the specified index into the entire
2420* 256-element palette: for instance, passing in a color of 17 would
2421* use color 1 of cset 1.
2422* Opacity controls how transparent the rectangle will be.
2423* You may use OP_TRANS (64) for a translucent (50%) image, or OP_OPAQUE (128)
2424* for an opaque (100%) image. Other values are **ignored**, and will be treated
2425* as translucent (OP_TRANS, or 64).
2426*
2427*/ Example Use: !#!
2428
2429/************************************************************************************************************/
2430
2431void Circle( int layer, int x, int y, int radius,
2432 int color, float scale,
2433 int rx, int ry, int rangle,
2434 bool fill, int opacity );
2435
2436
2437 ZASM Instruction:
2438 CIRCLE
2439 CIRCLER
2440
2441/**
2442* Draws a circle on the specified layer of the current screen with
2443* center (x,y) and radius scale*radius.
2444* Then performs a rotation counterclockwise, centered about the point
2445* (rx, ry), using an angle of rangle degrees.
2446* A filled circle is drawn if fill is true; otherwise, this method
2447* draws a wireframe.
2448* The circle is drawn using the specified index into the entire
2449* 256-element palette: for instance, passing in a color of 17 would
2450* use color 1 of cset 1.
2451* Opacity controls how transparent the circle will be.
2452* You may use OP_TRANS (64) for a translucent (50%) image, or OP_OPAQUE (128)
2453* for an opaque (100%) image. Other values are **ignored**, and will be treated
2454* as translucent (OP_TRANS, or 64).
2455*
2456*/ Example Use: !#!
2457
2458/************************************************************************************************************/
2459
2460void Arc( int layer, int x, int y, int radius, int startangle, int endangle,
2461 int color, float scale,
2462 int rx, int ry, int rangle,
2463 bool closed, bool fill, int opacity );
2464
2465 ZASM Instruction:
2466 ARC
2467 ARCR
2468
2469/**
2470* Draws an arc of a circle on the specified layer of the current
2471* screen. The circle in question has center (x,y) and radius
2472* scale*radius.
2473* The arc beings at startangle degrees counterclockwise from standard
2474* position, and ends at endangle degress counterclockwise from standard
2475* position. The behavior of this function is undefined unless
2476* 0 <= endangle-startangle < 360.
2477* The arc is then rotated about the point (rx, ry) using an angle of
2478* rangle radians.
2479* If closed is true, a line is drawn from the center of the circle to
2480* each endpoint of the arc, forming a sector of the circle. If fill
2481* is also true, a filled sector is drawn instead.
2482* The arc or sector is drawn using the specified index into the entire
2483* 256-element palette: for instance, passing in a color of 17 would
2484* use color 1 of cset 1.
2485* Opacity controls how transparent the arc will be.
2486* You may use OP_TRANS (64) for a translucent (50%) image, or OP_OPAQUE (128)
2487* for an opaque (100%) image. Other values are **ignored**, and will be treated
2488* as translucent (OP_TRANS, or 64).
2489*
2490*/ Example Use: !#!
2491
2492/************************************************************************************************************/
2493
2494void Ellipse( int layer, int x, int y, int xradius, int yradius,
2495 int color, float scale,
2496 int rx, int ry, int rangle,
2497 bool fill, int opacity);
2498
2499
2500
2501 ZASM Instruction:
2502 ELLIPSE2
2503 ELLIPSER
2504
2505/**
2506* Draws an ellipse on the specified layer of the current screen with
2507* center (x,y), x-axis radius xradius, and y-axis radius yradius.
2508* Then performs a rotation counterclockwise, centered about the point
2509* (rx, ry), using an angle of rangle degrees.
2510* A filled ellipse is drawn if fill is true; otherwise, this method
2511* draws a wireframe.
2512* The ellipse is drawn using the specified index into the entire
2513* 256-element palette: for instance, passing in a color of 17 would
2514* use color 1 of cset 1.
2515* Opacity controls how transparent the ellipse will be.
2516* You may use OP_TRANS (64) for a translucent (50%) image, or OP_OPAQUE (128)
2517* for an opaque (100%) image. Other values are **ignored**, and will be treated
2518* as translucent (OP_TRANS, or 64).
2519*
2520*/ Example Use: !#!
2521
2522/************************************************************************************************************/
2523
2524void Spline( int layer, int x1, int y1, int x2, int y2, int x3, int y3,int x4, int y4,
2525 int color, int opacity);
2526
2527 ZASM Instruction:
2528 SPLINER
2529 SPLINE
2530
2531/**
2532* Draws a cardinal spline on the specified layer of the current screen
2533* between (x1,y1) and (x4,y4)
2534* The spline is drawn using the specified index into the entire
2535* 256-element palette: for instance, passing in a color of 17 would
2536* use color 1 of cset 1.
2537* Opacity controls how transparent the ellipse will be.
2538* You may use OP_TRANS (64) for a translucent (50%) image, or OP_OPAQUE (128)
2539* for an opaque (100%) image. Other values are **ignored**, and will be treated
2540* as translucent (OP_TRANS, or 64).
2541*
2542*/ Example Use: !#!
2543
2544/************************************************************************************************************/
2545
2546void Line( int layer, int x, int y, int x2, int y2,
2547 int color, float scale,
2548 int rx, int ry, int rangle,
2549 int opacity );
2550
2551 ZASM Instruction:
2552 LINE
2553 LINER
2554/**
2555* Draws a line on the specified layer of the current screen between
2556* (x,y) and (x2,y2).
2557* Then scales the line uniformly by a factor of scale about the line's
2558* midpoint.
2559* Finally, performs a rotation counterclockwise, centered about the
2560* point (rx, ry), using an angle of rangle degrees.
2561* The line is drawn using the specified index into the entire
2562* 256-element palette: for instance, passing in a color of 17 would
2563* use color 1 of cset 1.
2564* Opacity controls how transparent the line will be.
2565* You may use OP_TRANS (64) for a translucent (50%) image, or OP_OPAQUE (128)
2566* for an opaque (100%) image. Other values are **ignored**, and will be treated
2567* as translucent (OP_TRANS, or 64).
2568*
2569*/ Example Use: !#!
2570
2571/************************************************************************************************************/
2572
2573void PutPixel (int layer, int x, int y,
2574 int color,
2575 int rx, int ry, int rangle,
2576 int opacity);
2577
2578 ZASM Instruction:
2579 PUTPIXEL
2580 PUTPIXELR
2581/**
2582* Draws a raw pixel on the specified layer of the current screen
2583* at (x,y).
2584* Then performs a rotation counterclockwise, centered about the point
2585* (rx, ry), using an angle of rangle degrees.
2586* The point is drawn using the specified index into the entire
2587* 256-element palette: for instance, passing in a color of 17 would
2588* use color 1 of cset 1.
2589* Opacity controls how transparent the point will be.
2590* You may use OP_TRANS (64) for a translucent (50%) image, or OP_OPAQUE (128)
2591* for an opaque (100%) image. Other values are **ignored**, and will be treated
2592* as translucent (OP_TRANS, or 64).
2593*
2594*/ Example Use: !#!
2595
2596/************************************************************************************************************/
2597
2598void DrawTile (int layer, int x, int y,
2599 int tile, int blockw, int blockh,
2600 int cset, int xscale, int yscale,
2601 int rx, int ry, int rangle,
2602 int flip,
2603 bool transparency, int opacity);
2604
2605 ZASM Instruction:
2606 DRAWTILE
2607 DRAWTILER
2608/**
2609* Draws a block of tiles on the specified layer of the current screen,
2610* starting at (x,y), using the specified cset.
2611* Starting with the specified tile, this method copies a block of size
2612* blockh x blockw from the tile sheet to the screen. This method's
2613* behavior is undefined unless 1 <= blockh, blockw <= 20.
2614* Scale specifies the actual size in pixels! So scale 1 would mean it is
2615* only one pixel in size. To use the default sizes of block w,h you must
2616* set xscale and yscale to -1. These values are not independant of one another,
2617* so you cannot set xscale and leave yscale at -1.
2618* rx, ry : these work now, just like the other primitives.
2619* rangle performs a rotation clockwise using an angle of rangle degrees.
2620* Flip specifies how the tiles should be flipped when drawn:
2621* 0: No flip
2622* 1: Horizontal flip
2623* 2: Vertical flip
2624* 3: Both (180 degree rotation)
2625* If transparency is true, the tiles' transparent regions will be
2626* respected.
2627* Opacity controls how transparent the solid portions of the tiles will
2628* be.
2629* You may use OP_TRANS (64) for a translucent (50%) image, or OP_OPAQUE (128)
2630* for an opaque (100%) image. Other values are **ignored**, and will be treated
2631* as translucent (OP_TRANS, or 64).
2632*/ Example Use: !#!
2633
2634/************************************************************************************************************/
2635
2636void FastTile (int layer, int x, int y,
2637 int tile, int cset,
2638 int opacity );
2639
2640 ZASM Instruction:
2641 FASTTILER
2642/**
2643* Optimized and simpler version of DrawTile()
2644* Draws a single tile on the current screen much in the same way as DrawTile().
2645* See DrawTile() for an explanation on what these arguments do.
2646*/ Example Use: !#!
2647
2648/************************************************************************************************************/
2649
2650void DrawCombo (int layer, int x, int y,
2651 int combo, int w, int h,
2652 int cset, int xscale, int yscale,
2653 int rx, int ry, int rangle,
2654 int frame, int flip,
2655 bool transparency, int opacity);
2656
2657 ZASM Instruction:
2658 DRAWCOMBO
2659 DRAWCOMBOR
2660/**
2661* Draws a combo on the specified layer of the current screen,
2662* starting at (x,y), using the specified cset.
2663* Starting with the specified tile referenced by the combo,
2664* this method copies a block of size
2665* blockh x blockw from the tile sheet to the screen. This method's
2666* behavior is undefined unless 1 <= blockh, blockw <= 20.
2667* Scale specifies the actual size in pixels! So scale 1 would mean it is
2668* only one pixel in size. To use the default sizes of block w,h you must
2669* set xscale and yscale to -1. These values are not independant of one another,
2670* so you cannot set xscale and leave yscale at -1.
2671* rx, ry : works now :
2672* rangle performs a rotation clockwise using an angle of rangle degrees.
2673* Flip specifies how the tiles should be flipped when drawn:
2674* 0: No flip
2675* 1: Horizontal flip
2676* 2: Vertical flip
2677* 3: Both (180 degree rotation)
2678* If transparency is true, the tiles' transparent regions will be
2679* respected.
2680* Opacity controls how transparent the solid portions of the tiles will
2681* be.
2682* You may use OP_TRANS (64) for a translucent (50%) image, or OP_OPAQUE (128)
2683* for an opaque (100%) image. Other values are **ignored**, and will be treated
2684* as translucent (OP_TRANS, or 64).
2685*/ Example Use: !#!
2686
2687/************************************************************************************************************/
2688
2689void FastCombo (int layer, int x, int y,
2690 int combo, int cset,
2691 int opacity );
2692
2693 ZASM Instruction:
2694 FASTCOMBOR
2695/**
2696* Optimized and simpler version of DrawCombo()
2697* Draws a single combo on the current screen much in the same way as DrawCombo().
2698* See DrawCombo() for an explanation on what these arguments do.
2699*/ Example Use: !#!
2700
2701/************************************************************************************************************/
2702
2703void DrawCharacter (int layer, int x, int y,
2704 int font, int color, int background_color,
2705 int width, int height, int glyph,
2706 int opacity );
2707
2708 ZASM Instruction:
2709 DRAWCHARR
2710/**
2711* Draws a single ASCII character 'glyph' on the specified layer of the current screen,
2712* using the specified font index (see std.zh for FONT_* list to pass to this method),
2713* starting at (x,y), using the specified color as the foreground color
2714* and background_color as the background color. * NOTE * Use -1 for a transparent background.
2715* The arguments width and height may be used to draw the glyph
2716* of any arbitrary size begining at 1 pixel up to 512 pixels large. (more than four times the size of the screen)
2717* Passing 0 or negative values to this will use the default fonts w and h.
2718* Opacity controls how transparent the is.
2719* You may use OP_TRANS (64) for a translucent (50%) image, or OP_OPAQUE (128)
2720* for an opaque (100%) image. Other values are **ignored**, and will be treated
2721* as translucent (OP_TRANS, or 64).
2722*/ Example Use: !#!
2723
2724/************************************************************************************************************/
2725
2726void DrawInteger (int layer, int x, int y,
2727 int font, int color, int background_color,
2728 int width, int height, int number, int number_decimal_places,
2729 int opacity);
2730
2731
2732 ZASM Instruction:
2733 DRAWINTR
2734/**
2735* Draws a zscript 'int' or 'float' on the specified layer of the current screen,
2736* using the specified font index (see std.zh for FONT_* list to pass to this method),
2737* starting at (x,y), using the specified color as the foreground color
2738* and background_color as the background color. * NOTE * Use -1 for a transparent background.
2739* The arguments width and height may be used to draw the number
2740* of any arbitrary size begining at 1 pixel up to 512 pixels large.
2741* Passing 0 or negative values to this will use the default fonts w and h.
2742* The number can be rendered as type 'int' or 'float' by setting the argument
2743* "number_decimal_places", which is only valid if set to 0 or <= 4.
2744* Opacity controls how transparent the is.
2745* You may use OP_TRANS (64) for a translucent (50%) image, or OP_OPAQUE (128)
2746* for an opaque (100%) image. Other values are **ignored**, and will be treated
2747* as translucent (OP_TRANS, or 64).
2748*/ Example Use: !#!
2749
2750/************************************************************************************************************/
2751
2752void DrawString( int layer, int x, int y,
2753 int font, int color, int background_color, int format,
2754 int ptr[],
2755 int opacity );
2756
2757 ZASM Instruction:
2758 DRAWSTRINGR
2759/**
2760* Prints a NULL terminated string up to 256 characters from an int array
2761* containing ASCII data (*ptr) on the specified layer of the current screen,
2762* using the specified font index (see std.zh for FONT_* list to pass to this method),
2763* using the specified color as the foreground color
2764* and background_color as the background color. * NOTE * Use -1 for a transparent background.
2765* The array pointer should be passed as the argument for '*ptr', ie.
2766* int string[] = "Example String"; Screen->DrawString(l,x,y,f,c,b_c,fo,o,string);
2767* int format tells the engine how to format the string. (see std.zh for TF_* list to pass to this method)
2768* Opacity controls how transparent the message is.
2769* You may use OP_TRANS (64) for a translucent (50%) image, or OP_OPAQUE (128)
2770* for an opaque (100%) image. Other values are **ignored**, and will be treated
2771* as translucent (OP_TRANS, or 64).
2772*/ Example Use: !#!
2773
2774/************************************************************************************************************/
2775
2776
2777
2778 /////////////////////////
2779 // (Psuedo) 3D drawing //
2780 /////////////////////////
2781
2782 //! When allocating a texture, the size (h,w) must be between 1 and 16, in powers of two.
2783 //! Thus, legal sizes are 1, 2, 4, 8, and 16.
2784 //! This applies to *all* the pseudo-3d and 3-D drawing functions.
2785
2786 void Quad ( int layer,
2787 int x1, int y1, int x2, int y2, int x3, int y3, int x4, int y4,
2788 int w, int h, int cset, int flip, int texture, int render_mode);
2789
2790 ZASM Instruction:
2791 QUADR
2792
2793 /**
2794 * Draws a quad on the specified layer with the corners x1,y1 through x4,y4.
2795 * Corners are drawn in a counterclockwise order starting from x1,y1. ( So
2796 * if you draw a "square" for example starting from the bottom-right corner
2797 * instead of the usual top-left, the the image will be textured onto the
2798 * quad so it appears upside-down. -yes, these are rotatable. )
2799 *
2800 * From there a single or block of tiles, combos **or a bitmap** is then texture mapped
2801 * onto the quad using the arguments w, h, cset, flip, and render_mode.
2802 * A positive vale in texture will draw the image from the tilesheet pages,
2803 * whereas a negative value will be drawn from the combo page. 0 will draw combo number 0.
2804 * Both w and h are undefined unless 1 <= blockh, blockw <= 16, and it is a power of
2805 * two. ie: 1, 2 are acceptable, but 2, 15 are not.
2806 *
2807 * To specify a bitmap as a texture, sum 65520 with the bitmap ID, or use the constant TEX_BITMAP + Bitmap
2808 * Example: Screen->Quad(6, 0, 0, 40, 25, 18, 50, 60, 110, 0, 0, 0, 0, TEX_BITMAP+RT_BITMAP0, PT_TEXTURE);
2809 *
2810 *
2811 * Flip specifies how the tiles/combos should be flipped when drawn:
2812 * 0: No flip
2813 * 1: Horizontal flip
2814 * 2: Vertical flip
2815 * 3: Both (180 degree rotation)
2816 * (!) See std.zh for a list of all available render_mode arguments.
2817 */ Example Use: !#!
2818
2819 /************************************************************************************************************/
2820
2821 void Triangle ( int layer,
2822 int x1, int y1, int x2, int y2, int x3, int y3,
2823 int w, int h, int cset, int flip, int texture, int render_mode);
2824
2825 ZASM Instruction:
2826 TRIANGLER
2827
2828 /**
2829 * Draws a triangle on the specified layer with the corners x1,y1 through x4,y4.
2830 * Corners are drawn in a counterclockwise order starting from x1,y1.
2831 * From there a single or block of tiles or combos is then texture mapped
2832 * onto the triangle using the arguments w, h, cset, flip, and render_mode.
2833 *
2834 * A positive value in texture will draw the image from the tilesheet pages,
2835 * whereas a negative value will be drawn from the combo page. 0 will draw combo number 0.
2836 * Both w and h are undefined unless 1 <= blockh, blockw <= 16, and it is a power of
2837 * two. ie: 1, 2 are acceptable, but 2, 15 are not.
2838 *
2839 * Flip specifies how the tiles/combos should be flipped when drawn:
2840 * 0: No flip
2841 * 1: Horizontal flip
2842 * 2: Vertical flip
2843 * 3: Both (180 degree rotation)
2844 * (!) See std.zh for a list of all available render_mode arguments.
2845 */ Example Use: !#!
2846
2847 /************************************************************************************************************/
2848
2849 void Triangle3D ( int layer,
2850 int pos[9], int uv[6], int csets[3], int size[2],
2851 int flip, int tile, int polytype );
2852
2853 ZASM Instruction:
2854 TRIANGLE3DR
2855 /**
2856 * Draws a 3d triangle on the specified layer with the corners x1,y1 through x4,y4.
2857 * Corners are drawn in a counterclockwise order starting from x1,y1.
2858 * From there a single or block of tiles or combos is then texture mapped
2859 * onto the triangle using the arguments w, h, cset, flip, and render_mode.
2860 *
2861 * A positive value in texture will draw the image from the tilesheet pages,
2862 * whereas a negative value will be drawn from the combo page. 0 will draw combo number 0.
2863 * Both w and h are undefined unless 1 <= blockh, blockw <= 16, and it is a power of
2864 * two. ie: 1, 2 are acceptable, but 2, 15 are not.
2865 *
2866 * Arguments take the form of array pointers: Thus, you must declare arrays with the values that you wish to use
2867 * and pass their pointers to each of the following:
2868 *
2869 * [9]pos - x, y, z positions of the 3 corners.
2870 * [6]uv - x, y texture coordinates of the given texture.
2871 * [3]csets - of the corners to interpolate between.
2872 * [2]size - w, h, of the texture.
2873 * w, and h must be in values of 1, 2, 4, 8, or 16.
2874 *
2875 *
2876 * Flip specifies how the tiles/combos should be flipped when drawn:
2877 * 0: No flip
2878 * 1: Horizontal flip
2879 * 2: Vertical flip
2880 * 3: Both (180 degree rotation)
2881 * (!) See std.zh for a list of all available render_mode arguments.
2882 */ Example Use: !#!
2883
2884 /************************************************************************************************************/
2885
2886 void Quad3D ( int layer,
2887 int pos[], int uv[], int cset[], int size[],
2888 int flip, int texture, int render_mode );
2889
2890 ZASM Instruction:
2891 QUAD3DR
2892
2893 /**
2894 * Draws a Quad on the specified layer similar to Quad.
2895 * Arguments take the form of array pointers: Thus, you must declare arrays with the values that you wish to use
2896 * and pass their pointers to each of the following:
2897 *
2898 * [12]pos - x, y, z positions of the 4 corners.
2899 * [8]uv - x, y texture coordinates of the given texture.
2900 * [4]csets - of the corners to interpolate between.
2901 * [2]size - w, h, of the texture.
2902 * w, and h must be in values of 1, 2, 4, 8, or 16.
2903 * (!) See std.zh for a list of all available render_mode arguments.
2904 */ Example Use: !#!
2905
2906 /************************************************************************************************************/
2907
2908 void SetRenderTarget( int bitmap_id );
2909
2910 ZASM Instruction:
2911 SETRENDERTARGET
2912
2913 /**
2914 * Sets the target bitmap for all succesive drawing commands.
2915 * These can be directly to the screen or any one of the available off-screen bitmaps,
2916 * which are generally categorized as -1(screen) or 0-bitmapNumber(off-screen).
2917 *
2918 * (!) See std.zh for a complete list of valid render targets (RT_*).
2919 */ Example Use: !#!
2920
2921 /************************************************************************************************************/
2922
2923 void DrawBitmap ( int layer,
2924 int bitmap_id,
2925 int source_x, int source_y, int source_w, int source_h,
2926 int dest_x, int dest_y, int dest_w, int dest_h,
2927 float rotation, bool mask);
2928
2929 ZASM Instruction:
2930 BITMAPR
2931
2932 /**
2933 * Draws a source rect from off-screen Bitmap with id of bitmap_id onto
2934 * an area of the screen described by dest rect at the given layer.
2935 *
2936 * (!) Note* Script drawing functions are enqueued and executed in a frame-by-frame basis
2937 * based on the order of which layer they need to be drawn to. Drawing to or from
2938 * seperate render tagets or bitmaps is no exception! So keep in mind in order to
2939 * eliminate unwanted drawing orders or bugs.
2940 */ Example Use:
2941 Screen->DrawBitmap( 6, myBitmapId, 0, 0, 16, 16, 79, 57, 32, 32, 0, true );
2942 This would draw a 16x16 area starting at the upper-left corner of source bitmap to
2943 layer 6 of the current screen at coordinates 79,57 with a width and height of
2944
2945
2946
2947 // Screen/Layer Drawing
2948 */
2949
2950 /************************************************************************************************************/
2951
2952 void DrawBitmapEx ( int layer,
2953 int bitmap_id,
2954 int source_x, int source_y, int source_w, int source_h,
2955 int dest_x, int dest_y, int dest_w, int dest_h,
2956 float rotation, int cx, int cy, int mode, int lit, bool mask);
2957
2958 ZASM: BITMAPEXR
2959
2960 /**
2961 *
2962 * As DrawBitmap(), except that it can do more things.
2963 *
2964 * The 'mode' parameter sets up drawing modes. AT PRESENT this supports normal opaque drawing as DrawBitmap()
2965 * AND it supports TRANSLUCENT MODE, which will allow drawing translucent bitmaps.
2966 * The translucent mode does not yet support rotation, and some other modes are temporarily suspended, pending
2967 * full implementation.
2968 *
2969 * See std_constants.zh, under BITDX_* (or possibly we'll change this to BMPDX_* later?) for a list of modes,
2970 * and more information
2971 *
2972 * Draws a source rect from off-screen Bitmap with id of bitmap_id onto
2973 * an area of the screen described by dest rect at the given layer.
2974 *
2975 * (!) Note* Script drawing functions are enqueued and executed in a frame-by-frame basis
2976 * based on the order of which layer they need to be drawn to. Drawing to or from
2977 * seperate render tagets or bitmaps is no exception! So keep in mind in order to
2978 * eliminate unwanted drawing orders or bugs.
2979 *
2980 * Set 'mode' to a value of '1' to draw a translucent bitmap.
2981 *
2982 * Note: Rotation does not work with translucent bitmaps at this time.
2983 *
2984 * cx, cy: Used for pivot
2985 * lit: used for lit colour in light table (may not work).
2986 *
2987 */ Example Use:
2988 Screen->DrawBitmapEx( 6, myBitmapId, 0, 0, 16, 16, 79, 57, 32, 32, 0, 1, true );
2989 This would draw a translucent 16x16 area starting at the upper-left corner of source
2990 bitmap to layer 6 of the current screen at coordinates 79,57 with a width and height of
2991
2992
2993
2994
2995 // Screen/Layer Drawing
2996 */
2997
2998 /************************************************************************************************************/
2999
3000 void DrawLayer (int layer,
3001 int source_map, int source_screen, int source_layer,
3002 int x, int y, float rotation, int opacity);
3003
3004 ZASM Instruction:
3005 DRAWLAYERR
3006
3007 /**
3008 * Draws an entire Layer from source_screen on source_map on the specified layer of the current screen at (x,y).
3009 * If rotation is not zero, it(the entire layer) will rotate about its center.
3010 *
3011 * Opacity controls how transparent the solid portions of the tiles will
3012 * You may use OP_TRANS (64) for a translucent (50%) image, or OP_OPAQUE (128)
3013 * for an opaque (100%) image. Other values are **ignored**, and will be treated
3014 * as translucent (OP_TRANS, or 64).
3015 *
3016 * Also see ScreenToLayer() in std.zh
3017 */ Example Use:
3018
3019 /************************************************************************************************************/
3020
3021 void DrawScreen (int layer,
3022 int map, int source_screen,
3023 int x, int y, float rotation);
3024
3025 ZASM Instruction:
3026 DRAWSCREENR
3027
3028 /**
3029 * Draws an entire screen from screen on map on the specified layer of the current screen at (x,y).
3030 * If rotation is not zero, it(the entire screen) will rotate about its center.
3031 *
3032 */ Example Use:
3033
3034/************************************************************************************************************/
3035/************************************************************************************************************/
3036
3037
3038
3039//===================================
3040//--- FFC Functions and Variables ---
3041//===================================
3042
3043 class ffc
3044
3045/*
3046* The following functions, and arrays are part of the ffc class.
3047*
3048* Ordinarily, these are set when writing an ffc script, using the pointer
3049* this->
3050* Example: this->Data = 10; Sets the Data variable for the present ffc
3051* to a value of '10'.
3052*
3053* The 'this->' pointer is used in ffcs, and item scripts only. It references ffc
3054* variables and arrays in an ffc script; and itemdata variables in an item script.
3055*
3056* Changing ffc variables without 'this->':
3057*
3058* You may change a variable, or array value of the ffc class by loading the ffc into a custom pointer
3059* using Screen->LoadFFC(int number) as follows:
3060*
3061* ffc f; //Declare a general ffc pointer.
3062* //You must use the ffc token to declare the pointer, but you may use any
3063* //name that you desire for it. 'f' here, is merely a short-name example.
3064*
3065* f = Screen->LoadFFC(10); //Loads the data of ffc ID 10 for the present screen into the 'f' pointer.
3066*
3067* f->Data = 15; //Sets the 'Data' variable of the ffc to a value of '15'.
3068*
3069* f->X = 120; //Sets the X-position of the ffc assigned to pointer 'f' to a value of '120'.
3070*/
3071
3072
3073Set Working FFC ID: ZASM Instruction
3074 REFFFC
3075
3076/************************************************************************************************************/
3077
3078
3079int Data; ZASM Instruction:
3080 DATA<d3>
3081
3082/**
3083* The number of the combo associated with this FFC.
3084*/ Example Use:
3085
3086 f->Data = 10;
3087 Sets the ffc to Combo 10.
3088
3089/************************************************************************************************************/
3090
3091int Script; ZASM Instruction:
3092 FFSCRIPT<d3>
3093
3094/**
3095* The number of the script assigned to the FFC. This will be automatically
3096* set to 0 when the FFC's script halts. A script cannot change the script of
3097* the FFC running it; in other words, f->Script is read-only when f==this.
3098* When an FFC's script is changed, its arguments, Misc[], and registers will
3099* all be set to 0, and it will start running from the beginning. Set
3100* ffc->InitD[] after setting the script before the script starts running
3101* to pass arguments to it.
3102*
3103*/ Example Use:
3104
3105 f->Script = 10;
3106 Sets the ffc to Combo 10.
3107
3108/************************************************************************************************************/
3109
3110int CSet; ZASM Instruction:
3111 FCSET<d3>
3112
3113/**
3114* The cset of the FFC.
3115*
3116*/ Example Use:
3117
3118 f->CSet = 2;
3119 Sets the ffc to CSet 2.
3120
3121/************************************************************************************************************/
3122
3123int Delay; ZASM Instruction:
3124 DELAY<d3>
3125
3126/**
3127* The FFC's animation delay, in frames.
3128*
3129*/ Example Use:
3130
3131 f->Delay = 120;
3132 120 frames will pass before the ffc animates.
3133
3134/************************************************************************************************************/
3135
3136float X; ZASM Instruction:
3137 FX<d3>
3138
3139/**
3140* The FFC's X position on the screen.
3141*
3142* Values outside the screen boundaries *are* legal.
3143*
3144*/ Example Use:
3145
3146 f->X = 43;
3147 Sets the ffc at X-position 43; 43 pixels to the right of the leftmost screen edge.
3148
3149/************************************************************************************************************/
3150
3151float Y; ZASM Instruction:
3152 FY<d3>
3153
3154/**
3155* The FFC's Y position on the screen.
3156*
3157* Values outside the screen boundaries *are* legal.
3158* The Y value 0 is automatically offset to account for the passive subscreen.
3159* To place an ffc in the area of the passive subscreen, a negative value must be passed to Y.
3160*
3161*/ Example Use:
3162
3163 f->X = 90;
3164 Sets the ffc at Y-position to 90; i.e. 90 pixels below the passive subscreen.
3165
3166/************************************************************************************************************/
3167
3168float Vx; ZASM Instruction:
3169 XD<d3>
3170
3171/**
3172* The FFC's velocity's X-component.
3173*
3174*
3175*/ Example Use:
3176
3177 f->Vx = 20;
3178 The ffc will move by 20 pixels per second on the X avis.
3179
3180/************************************************************************************************************/
3181
3182float Vy; ZASM Instruction:
3183 YD<d3>
3184
3185/**
3186* The FFC's velocity's Y-component.
3187*
3188*
3189*/ Example Use:
3190
3191 f->Vy = 20;
3192 The ffc will move by 20 pixels per second on the Y avis.
3193
3194/************************************************************************************************************/
3195
3196float Ax; ZASM Instruction:
3197 XD2<d3>
3198
3199/**
3200* The FFC's acceleration's X-component.
3201*
3202*
3203*/ Example Use:
3204
3205 f->Vx = 1.03;
3206 Every frame, the velocity X-component will increase by 1.03.
3207
3208/************************************************************************************************************/
3209
3210float Ay; ZASM Instruction:
3211 YD2<d3>
3212
3213/**
3214* The FFC's acceleration's Y-component.
3215*
3216*
3217*/ Example Use:
3218
3219 f->Vx = 0.2903;
3220 Every frame, the velocity Y-component will increase by 0.2903.
3221
3222/************************************************************************************************************/
3223
3224bool Flags[]; ZASM Instruction:
3225 FLAG<d3>
3226 FFFLAGSD
3227
3228
3229/**
3230* The FFC's set of flags. Use the FFCF_ constants in std.zh as the
3231* index to access a particular flag.
3232*
3233*/ Example Use: !#!
3234
3235/************************************************************************************************************/
3236
3237int TileWidth; ZASM Instruction:
3238 FFTWIDTH<d3>
3239 WIDTH<>
3240
3241/**
3242* The number of tile columns composing the FFC.
3243* The maximum value is '4'.
3244*
3245*/ Example Use: !#!
3246
3247/************************************************************************************************************/
3248
3249int TileHeight; ZASM Instruction:
3250 FFTHEIGHT<d3>
3251 HEIGHT<>
3252
3253/**
3254* The number of tile rows composing the FFC.
3255* The maximum value is '4'.
3256*
3257*/ Example Use: !#!
3258
3259/************************************************************************************************************/
3260
3261int EffectWidth; ZASM Instruction:
3262 FFCWIDTH<d3>
3263
3264/**
3265* The width (in pixels) of the area of effect of the combo associated with the FFC.
3266* The maximum value is '64'.
3267*
3268*/ Example Use: !#!
3269
3270/************************************************************************************************************/
3271
3272int EffectHeight; ZASM Instruction:
3273 FFCHEIGHT<d3>
3274
3275/**
3276* The width (in pixels) of the area of effect of the combo associated with the FFC.
3277* The maximum value is '64'.
3278*
3279*/ Example Use: !#!
3280
3281/************************************************************************************************************/
3282
3283int Link; ZASM Instruction:
3284 FFLINK<d3>
3285 LINK<>
3286
3287/**
3288* The number of the FFC linked to by this FFC.
3289*
3290*/ Example Use: !#!
3291
3292/************************************************************************************************************/
3293
3294float InitD[8]; ZASM Instruction:
3295 FFINITD<>
3296 FFINITDD<>?
3297 D<>
3298
3299/**
3300* The original values of the FFC's 8 D input values as they are stored in
3301* the .qst file, regardless of whether they have been modified by ZScript.
3302*
3303*/ Example Use: !#!
3304
3305/************************************************************************************************************/
3306
3307float Misc[16]; ZASM Instruction:
3308 FFMISC
3309 FFMISCD
3310
3311/**
3312* An array of 16 miscellaneous variables for you to use as you please.
3313* These variables are not saved with the ffc.
3314*
3315*/ Example Use: !#!
3316
3317/************************************************************************************************************/
3318
3319Address Argument ZASM Instruction
3320 A<>
3321
3322/************************************************************************************************************/
3323/************************************************************************************************************/
3324
3325
3326
3327
3328
3329//====================================
3330//--- Link Functions and Variables ---
3331//====================================
3332
3333 namespace Link
3334
3335
3336int X; ZASM Instruction:
3337 LINKX
3338
3339/**
3340* Link's X position on the screen, in pixels. Float values passed to this will be truncated to ints.
3341*
3342*/ Example Use: !#!
3343
3344/************************************************************************************************************/
3345
3346int Y; ZASM Instruction:
3347 LINKY
3348
3349/**
3350* Link's Y position on the screen, in pixels. Float values passed to this will be truncated to ints.
3351*
3352*/ Example Use: !#!
3353
3354/************************************************************************************************************/
3355
3356int Z; ZASM Instruction:
3357 LINKZ
3358
3359/**
3360* Link's Z position on the screen, in pixels. Float values passed to this will be truncated to ints.
3361*
3362*/ Example Use: !#!
3363
3364/************************************************************************************************************/
3365
3366bool Invisible; ZASM Instruction:
3367 LINKINVIS
3368
3369/**
3370* Whether Link is currently being draw to the screen. Set true to remove him from view.
3371*
3372*/ Example Use: !#!
3373
3374/************************************************************************************************************/
3375
3376bool CollDetection; ZASM Instruction:
3377 LINKINVINC
3378
3379/**
3380* If true, Link's collision detection with npcs and eweapons is currently turned off.
3381* This variable works on a different system to clocks and the level 4 cheat, so it will not
3382* necessarily return true if they are set.
3383*
3384*/ Example Use: !#!
3385
3386/************************************************************************************************************/
3387
3388int Jump; ZASM Instruction:
3389 LINKJUMP
3390
3391/**
3392* Link's upward velocity, in pixels. If negative, Link will fall.
3393* The downward acceleration of Gravity (in Init Data) modifies this value every frame.
3394*
3395* This value is intended to be in pixels, but appears to be in tiles. ?!
3396*
3397*/ Example Use: !#!
3398
3399/************************************************************************************************************/
3400
3401int SwordJinx; ZASM Instruction:
3402 LINKSWORDJINX
3403
3404/**
3405* The time, in frames, until Link regains use of his sword. -1 signifies
3406* a permanent loss of the sword caused by a Red Bubble.
3407*
3408*/ Example Use: !#!
3409
3410/************************************************************************************************************/
3411
3412int ItemJinx; ZASM Instruction:
3413 LINKITEMJINX
3414
3415/**
3416* The time, in frames, until Link regains use of his items. -1 signifies
3417* a permanent loss of his items. caused by a Red Bubble.
3418*
3419*/ Example Use: !#!
3420
3421/************************************************************************************************************/
3422
3423int Drunk; ZASM Instruction:
3424 LINKDRUNK
3425
3426/**
3427* The time, in frames, that Link will be 'drunk'. If positive, the player's
3428* controls are randomly interfered with, causing Link to move erratically.
3429* This value is decremented once per frame. As the value of Drunk approaches 0,
3430* the intensity of the effect decreases.
3431*
3432*/ Example Use: !#!
3433
3434/************************************************************************************************************/
3435
3436int Dir; ZASM Instruction:
3437 LINKDIR
3438
3439/**
3440* The direction Link is facing. Use the DIR_ constants in std.zh to set
3441* or compare this variable. Note: even though Link can move diagonally if the
3442* quest allows it, his sprite doesn't ever use any of the diagonal directions,
3443* which are intended for enemies only.
3444*
3445* Reading this value occurs after Waitdraw().
3446*
3447*/ Example Use: !#!
3448
3449/************************************************************************************************************/
3450
3451int HitDir; ZASM Instruction:
3452 LINKHITDIR
3453
3454/**
3455* The direction Link should bounce in when he is hit. This is mostly useful for
3456* simulating getting hit by setting Link->Action to LA_GOTHURTLAND.
3457*
3458* This value does nothing if Link->Action does not equal LA_GOTHURTLAND or LA_GOTHURTWATER.
3459* Forcing this value to -1 prevent Link from being knocked back when injured, or when touching any enemy.
3460*
3461*/ Example Use: !#!
3462
3463/************************************************************************************************************/
3464
3465int WarpEffect; ZASM Instruction:
3466 WARPEFFECT
3467
3468/**
3469* Sets a warp effect type prior to doing Screen->Warp
3470* These replicate the in-build effects for tile warps.
3471* see 'std_constants.zh' under WARPFX_* for a list of effects.
3472*
3473*/ Example Use: !#!
3474
3475/************************************************************************************************************/
3476
3477int WarpSound; ZASM Instruction:
3478 LINKWARPSOUND
3479
3480/**
3481* Setting this to a value other than '0' will play that sound when Link warps.
3482*
3483*/ Example Use: !#!
3484
3485/************************************************************************************************************/
3486
3487bool SideWarpSounds; ZASM Instruction:
3488 PLAYWARPSOUND
3489
3490/**
3491* By default, even if you set a warp sound, it will not play in sidewarps.
3492* If you enable this setting, the sound will play in side warps.
3493* At present, this does not disable playing the sound otherwise. Set Link->WarpSound = 0 to do that.
3494*
3495*/ Example Use: !#!
3496
3497/************************************************************************************************************/
3498
3499bool PitWarpSounds; ZASM Instruction:
3500 PLAYPITWARPSFX
3501
3502/**
3503* By default, even if you set a warp sound, it will not play in pit warps.
3504* If you enable this setting, the sound will play in a pit warp, one time.
3505* This value resets after the pit warp, so it is mandatory to re-set it each time tat you desire a pit warp
3506* to play a sound. Do this before Waitdraw().
3507*
3508*/ Example Use: !#!
3509
3510/************************************************************************************************************/
3511
3512int UseWarpReturn; ZASM Instruction:
3513 LINKRETSQUARE
3514
3515/**
3516* Setting this to a value between 0 and 3 will change the target return square for Link->Warp
3517* Valid values are: 0 (A), 1 (B), 2 (C), and 3 (D). Other values will be clamed within this range.
3518*
3519*/ Example Use: !#!
3520
3521/************************************************************************************************************/
3522
3523int UsingItem; ZASM Instruction:
3524 LINKUSINITEM
3525
3526/**
3527* Returns the ID of an item used when Link uses an item.
3528* Returns -1 if Link is not using an item this frame.
3529* Does not work at present.
3530*
3531*/ Example Use: !#!
3532
3533/************************************************************************************************************/
3534
3535int UsingItemA; ZASM Instruction:
3536 LINKUSINITEMA
3537
3538/**
3539* Returns the ID of an item used when Link uses an item on button A.
3540* Returns -1 if Link is not using an item this frame.
3541* Does not work at present.
3542*
3543*/ Example Use: !#!
3544
3545/************************************************************************************************************/
3546
3547int UsingItemB; ZASM Instruction:
3548 LINKUSINITEMB
3549
3550/**
3551* Returns the ID of an item used when Link uses an item on button B.
3552* Returns -1 if Link is not using an item this frame.
3553* Does not work at present.
3554*
3555*/ Example Use: !#!
3556
3557/************************************************************************************************************/
3558
3559bool Diagonal; ZASM Instruction:
3560 LINKDIAG
3561
3562/**
3563* This corresponds to whether 'Diagonal Movement' is enabled, or not.
3564* This will initially return true, or false, based on the setting in Quest->Graphics->Sprites->Link.
3565* You may enable, or disable diagonal movement by writing to this value.
3566*
3567*/ Example Use: !#!
3568
3569/************************************************************************************************************/
3570
3571bool BigHitbox; ZASM Instruction:
3572 LINKBIGHITBOX
3573
3574/**
3575* This corresponds to whether 'Big Hitbox' is enabled, or not.
3576* This will initially return true, or false, based on the setting in Quest->Graphics->Sprites->Link.
3577* You may enable, or disable big hitbox, by writing to this value.
3578*
3579*/ Example Use: !#!
3580
3581/************************************************************************************************************/
3582
3583int HP; ZASM Instruction:
3584 LINKHP
3585
3586/**
3587* Link's current hitpoints, in 16ths of a heart.
3588*
3589*/ Example Use: !#!
3590
3591/************************************************************************************************************/
3592
3593int MP; ZASM Instruction:
3594 LINKMP
3595
3596/**
3597* Link's current amount of magic, in 32nds of a magic block.
3598*
3599*/ Example Use: !#!
3600
3601/************************************************************************************************************/
3602
3603int MaxHP; ZASM Instruction:
3604 LINKMAXHP
3605
3606/**
3607* Link's maximum hitpoints, in 16ths of a heart.
3608*
3609*/ Example Use: !#!
3610
3611/************************************************************************************************************/
3612
3613int MaxMP; ZASM Instruction:
3614 LINKMAXMP
3615
3616/**
3617* Link's maximum amount of magic, in 32nds of a magic block.
3618*
3619*/ Example Use: !#!
3620
3621/************************************************************************************************************/
3622
3623int Action; ZASM Instruction:
3624 LINKACTION<>
3625
3626/**
3627* Link's current action. Use the LA_ constants in std.zh to set or
3628* compare this value.
3629* This value is read-write, but writing some actions are undefined in this
3630* version of ZC. The following are known to work if you write to them:
3631*
3632* LA_NONE
3633* LA_WALKING
3634* LA_ATTACKING
3635* LA_FROZEN //Verify
3636* LA_HOLD1LAND
3637* LA_HOLD2LAND
3638* LA_GOTHURTLAND
3639* LA_SWIMMING
3640* LA_GOTHURTWATER
3641* LA_HOLD1WATER
3642* LA_HOLD2WATER
3643* LA_CASTING
3644* LA_DROWNING
3645* LA_CHARGING //Resets chargeclock?
3646* LA_SPINNING //Resets spinclock?
3647* LA_DIVING //Verify
3648*
3649*/ Example Use: !#!
3650
3651/************************************************************************************************************/
3652
3653int HeldItem; ZASM Instruction:
3654 LINKHELD<>
3655
3656/**
3657* Link's current action. Use the LA_ constants in std.zh to set or
3658* The item that Link is currently holding up; reading or setting this
3659* field is undefined if Link's action is not current a hold action.
3660* Use the I_ constants in std.zh to specify the item, or -1 to show
3661* no item. Setting HeldItem to values other than -1 or a valid item
3662* ID is undefined.
3663*
3664*/ Example Use: !#!
3665
3666/************************************************************************************************************/
3667
3668int LadderX; ZASM Instruction:
3669 LINKLADDERX
3670
3671/**
3672* The X position of Link's stepladder, or 0 if no ladder is onscreen.
3673* This is read-only; while setting it is not syntactically incorrect, it does nothing.
3674*
3675*/ Example Use: !#!
3676
3677/************************************************************************************************************/
3678
3679int LadderY; ZASM Instruction:
3680 LINKLADDERY
3681
3682/**
3683* The Y position of Link's stepladder, or 0 if no ladder is onscreen.
3684* This is read-only; while setting it is not syntactically incorrect, it does nothing.
3685*
3686*/ Example Use: !#!
3687
3688/************************************************************************************************************/
3689
3690
3691
3692 *** Input Functions ***
3693 * The following Input* boolean values return true if the player is pressing
3694 * the corresponding button, analog stick, or key. Writing to this variable simulates
3695 * the press or release of that referenced button, analog stick, or key.
3696 */
3697
3698 bool InputStart; ZASM: INPUTSTART
3699
3700 bool InputMap; ZASM: INPUTMAP
3701
3702 bool InputUp; ZASM: INPUTUP
3703
3704 bool InputDown; ZASM: INPUTDOWN
3705
3706 bool InputLeft; ZASM: INPUTLEFT
3707
3708 bool InputRight; ZASM: INPUTRIGHT
3709
3710 bool InputA; ZASM: INPUTA
3711
3712 bool InputB; ZASM: INPUTB
3713
3714 bool InputL; ZASM: INPUTL
3715
3716 bool InputR; ZASM: INPUTR
3717
3718 bool InputEx1 ZASM: INPUTEX1
3719
3720 bool InputEx2 ZASM: INPUTEX2
3721
3722 bool InputEx3 ZASM: INPUTEX3
3723
3724 bool InputEx4 ZASM: INPUTEX4
3725
3726 bool InputAxisUp; ZASM: INPUTAXISUP
3727
3728 bool InputAxisDown; ZASM: INPUTAXISDOWN
3729
3730 bool InputAxisLeft; ZASM: INPUTAXISLEFT
3731
3732 bool InputAxisRight; ZASM: INPUTAXISRIGHT
3733
3734
3735 *** Press Functions ***
3736 /**
3737 * The following Press* boolean values return true if the player activated
3738 * the corresponding button, analog stick, or key this frame. Writing to this
3739 * variable simulates the press or release of that referenced button, analog stick,
3740 * or keys input press state.
3741 */
3742
3743
3744 bool PressStart; ZASM: INPUTPRESSSTART
3745
3746 bool PressMap; ZASM: INPUTPRESSMAP
3747
3748 bool PressUp; ZASM: INPUTPRESSUP
3749
3750 bool PressDown; ZASM: INPUTPRESSDOWN
3751
3752 bool PressLeft; ZASM: INPUTPRESSLEFT
3753
3754 bool PressRight; ZASM: INPUTPRESSRIGHT
3755
3756 bool PressA; ZASM: INPUTPRESSA
3757
3758 bool PressB; ZASM: INPUTPRESSB
3759
3760 bool PressL; ZASM: INPUTPRESSL
3761
3762 bool PressR; ZASM: INPUTPRESSR
3763
3764 bool PressEx1 ZASM: INPUTPRESSEX1
3765
3766 bool PressEx2 ZASM: INPUTPRESSEX2
3767
3768 bool PressEx3 ZASM: INPUTPRESSEX3
3769
3770 bool PressEx4 ZASM: INPUTPRESSEX4
3771
3772 bool PressAxisUp; ZASM: PRESSAXISUP
3773
3774 bool PressAxisDown; ZASM: PRESSAXISDOWN
3775
3776 bool PressAxisLeft; ZASM: PRESSAXISLEFT
3777
3778 bool PressAxisRight; ZASM: PRESSAXISRIGHT
3779
3780/************************************************************************************************************/
3781
3782int InputMouseX; ZASM Instruction:
3783 INPUTMOUSEX
3784
3785/**
3786* The mouse's in-game X position. This value is undefined if
3787* the mouse pointer is outside the Zelda Classic window.
3788*
3789*/ Example Use: !#!
3790
3791/************************************************************************************************************/
3792
3793int InputMouseY; ZASM Instruction:
3794 INPUTMOUSEY
3795
3796/**
3797* The mouse's in-game Y position. This value is undefined if
3798* the mouse pointer is outside the Zelda Classic window.
3799*
3800*/ Example Use: !#!
3801
3802/************************************************************************************************************/
3803
3804int InputMouseB; ZASM Instruction:
3805 INPUTMOUSEB
3806
3807/**
3808* Whether the left or right mouse buttons are pressed, as two flags OR'd (|) together;
3809* use the MB_ constants or the Input'X'Click functions in std.zh to check the button states.
3810* InputMouseB is read only; while setting it is not syntactically incorrect, it does nothing
3811* If you are not comfortable with binary, you can use the InputMouse'x' functions in std.zh
3812*
3813*/ Example Use: !#!
3814
3815/************************************************************************************************************/
3816
3817int InputMouseZ; ZASM Instruction:
3818 INPUTMOUSEB
3819
3820/**
3821* The current state of the mouse's scroll wheel, negative for scrolling down and positive for scrolling up.
3822*
3823*/ Example Use: !#!
3824
3825/************************************************************************************************************/
3826
3827bool Item[256]; ZASM Instruction:
3828 LINKITEMD
3829
3830/**
3831* True if Link's inventory contains the item whose ID is the index of
3832* the array access. Use the I_ constants in std.zh as an index into this array.
3833*
3834*/ Example Use: !#!
3835
3836/************************************************************************************************************/
3837
3838int Equipment; ZASM Instruction:
3839 LINKEQUIP
3840
3841/**
3842* Contains the item IDs of what is currently equiped to Link's A and B buttons.
3843* The first 8 bits contain the A button item, and the second 8 bits contain the B button item.
3844* If you are not comfortable with performing binary operations,
3845* you can use the functions GetEquipmentA() or GetEquipmentB() in std.zh.
3846*
3847*/ Example Use: !#!
3848
3849/************************************************************************************************************/
3850
3851int ItemA; ZASM Instruction:
3852 LINKITEMA
3853
3854/**
3855* Contains the item IDs of what is currently equiped to Link's A button.
3856* Writing to this variable will set an item to the A-button.
3857* This will occur even if the item is not in inventory, and not on the subscreen.
3858* This will ignore if you have B+A or B-only subscreens, and force-set the item.
3859* The intent of this is to allow scriters to easily create scripted subscreens.
3860*
3861*/ Example Use: !#!
3862
3863/************************************************************************************************************/
3864
3865int ItemB; ZASM Instruction:
3866 LINKITEMB
3867
3868/**
3869* Contains the item IDs of what is currently equiped to Link's B button.
3870* Writing to this variable will set an item to the A-button.
3871* This will occur even if the item is not in inventory, and not on the subscreen.
3872* The intent of this is to allow scriters to easily create scripted subscreens.
3873*
3874*/ Example Use: !#!
3875
3876/************************************************************************************************************/
3877//! Untested
3878int SetItemSlot(int itm_id, bool a_button, bool force);
3879 ZASM Instruction:
3880 LINKITEMB
3881
3882/**
3883* This allows you to set Link's button items without binary operations, and to decide whether to
3884* obey quest rules, or inventory.
3885*
3886* When using this, 'itm_id' is the ID number of the item.
3887* Set 'a_button' true to set this item to the A-button, false to set it to the B-button.
3888* Set' force' true to set the item even if Link does not have it, or if the Quest Rules disallow it.
3889* Otherwise, set 'force' false, and the item will only be set if Link has it. Furthermore
3890* it will only set to slot A if either it is a sword, or the B+A quest rule is enabled.
3891*
3892*/ Example Use: !#!
3893
3894/************************************************************************************************************/
3895
3896int Tile; ZASM Instruction:
3897 LINKTILE
3898
3899/**
3900* The current tile associated with Link. The effect of writing to this variable is undefined.
3901* Because Link's tile is not determined until he is drawn, this will actually represent
3902* Link's tile in the previous frame.
3903*
3904*/ Example Use: !#!
3905
3906/************************************************************************************************************/
3907
3908int Flip; ZASM Instruction:
3909 LINKFLIP
3910
3911/**
3912* The flip value of current tile associated with Link.
3913* The effect of writing to this variable is undefined (will do nothing).
3914* Because Link's tile is not determined until he is drawn, this will actually represent
3915* Link's tile flip in the previous frame.
3916*
3917*/ Example Use: !#!
3918
3919
3920/************************************************************************************************************/
3921
3922int Eaten; ZASM Instruction:
3923 LINKEATEN
3924
3925/**
3926* This stores a counter for how long Link has been inside a LikeLike, or similar enemy.
3927* It returns 0 if Link is not eaten, otherwise it returns the duration of him being eaten.
3928*
3929*/ Example Use: !#!
3930
3931/************************************************************************************************************/
3932
3933//Implemented, but does nothing. The opcodes are unfinished.
3934void SetTile(int sprite, int tile, int dir, int flip)
3935 ZASM Instruction:
3936 LINKSETTILE
3937
3938/**
3939* Sets the tile for Link's various actions.
3940* 'sprite' is the action for the tile. See Quest->Graphics->Sprites->Link for a visual reference.
3941* 'tile is the base tile for the sequence. It uses the animation style set in the sprites editor.
3942* 'dir' is the direction for the tile.
3943* 'flip' is the flip attribute for the tile.
3944* See 'std_constants' entries under LSPR_* for a list of the various attributes for 'sprite'.
3945*/
3946
3947/************************************************************************************************************/
3948//!Implemented, but the opcodes are unfinished, so it does not yet work as intended.
3949int GetLinkExtend(int sprite, int dir);
3950 ZASM Instruction:
3951 LINKGETEXTEND
3952
3953/**
3954* Gets the extend value for one of Link's various actions.
3955* This is equivalent to the Extend value set in Quest->Graphics->Sprites->Link when selecting a tile.
3956* See 'std_constants' entries under LSPR_* for a list of the various attributes for 'sprite'.
3957*/
3958
3959/************************************************************************************************************/
3960//!Implemented, but the opcodes are unfinished, so it does not yet work as intended.
3961void SetLinkExtend(int sprite, int dir, int extend);
3962 ZASM Instruction:
3963 LINKSETEXTEND
3964
3965/**
3966* Sets the extend value for one of Link's various actions.
3967* This is equivalent to the Extend value set in Quest->Graphics->Sprites->Link when selecting a tile.
3968* See 'std_constants' entries under LSPR_* for a list of the various attributes for 'sprite'.
3969*/
3970
3971/************************************************************************************************************/
3972//!Not implemented.
3973int GetTile(int sprite, int dir, int flip)
3974 ZASM Instruction:
3975 LINKGETTILE
3976
3977/**
3978* Returns the tile for one of Link's various actions.
3979* 'sprite' is the action for the tile. See Quest->Graphics->Sprites->Link for a visual reference.
3980* 'dir' is the direction for the tile.
3981* 'flip' is the flip attribute for the tile.
3982* See 'std_constants' entries under LSPR_* for a list of the various attributes for 'sprite'.
3983*/
3984
3985/************************************************************************************************************/
3986
3987int Extend; ZASM Instruction:
3988 LINKEXTEND
3989
3990/**
3991* Sets the extend value for all of Link's various actions.
3992* This is equivalent to the Extend value set in Quest->Graphics->Sprites->Link when selecting
3993* a tile, click on his sprites for any given action, and press the 'x' key.
3994* The options are 16x16, 16x32, and 32x32; which correspond to Extend values of ( 0, 1, and 2 )
3995* respectively.
3996*
3997* If used to check, this will return the value of the LSPR_NORMAL entry.
3998*/
3999
4000/************************************************************************************************************/
4001
4002int HitHeight; ZASM Instruction:
4003 LINKHYSZ
4004
4005/**
4006* link's Hitbox height in pixels.
4007* This is not usable, as Link->Extend cannot be set.
4008* While setting it is not syntactically incorrect, it does nothing.
4009* You can read a value that you assign to this (e.g. for custom collision functions).
4010* This value is not preserved through sessions: Loading a saved game will reset it to the default.
4011*
4012*/ Example Use: !#!
4013
4014/************************************************************************************************************/
4015
4016int HitWidth; ZASM Instruction:
4017 LINKHXSZ
4018
4019/**
4020* link's Hitbox width in pixels.
4021* This is not usable, as Link->Extend cannot be set.
4022* While setting it is not syntactically incorrect, it does nothing.
4023* You can read a value that you assign to this (e.g. for custom collision functions).
4024* This value is not preserved through sessions: Loading a saved game will reset it to the default.
4025*
4026*/ Example Use: !#!
4027
4028/************************************************************************************************************/
4029
4030int TileWidth; ZASM Instruction:
4031 LINKTYSZ
4032/**
4033* Link's width, in tiles.
4034* This is not usable, as Link->Extend cannot be set.
4035* While setting it is not syntactically incorrect, it does nothing.
4036* You can read a value that you assign to this (e.g. for custom/proxy sprite drawing).
4037* This value is not preserved through sessions: Loading a saved game will reset it to the default.
4038*
4039*/ Example Use: !#!
4040
4041/************************************************************************************************************/
4042
4043int TileHeight; ZASM Instruction:
4044 LINKTXSZ
4045
4046/**
4047* Link's height, in tiles.
4048* This is not usable, as Link->Extend cannot be set.
4049* While setting it is not syntactically incorrect, it does nothing.
4050* You can read a value that you assign to this (e.g. for custom/proxy sprite drawing).
4051* This value is not preserved through sessions: Loading a saved game will reset it to the default.
4052*
4053*/ Example Use: !#!
4054
4055/************************************************************************************************************/
4056
4057int HitZHeight; ZASM Instruction:
4058 LINKHZSZ
4059
4060/**
4061* The Z-axis height of Link's hitbox, or collision rectangle.
4062* The lower it is, the lower a flying or jumping enemy must fly in order to hit Link.
4063* To jump over a sprite, you must be higher than its Z + HitZHeight.
4064* The values of DrawZOffset and HitZHeight are linked. Setting one, also sets the other.
4065* Writing to this is ignored unless Extend is set to values >=3.
4066* This is not usable, as Link->Extend cannot be set.
4067* While setting it is not syntactically incorrect, it does nothing.
4068* You can read a value that you assign to this (e.g. for custom collision functions).
4069* This value is not preserved through sessions: Loading a saved game will reset it to the default.
4070*
4071*/ Example Use: !#!
4072
4073/************************************************************************************************************/
4074
4075int HitXOffset; ZASM Instruction:
4076 LINKHXOFS
4077
4078/**
4079* The X offset of Link's hitbox, or collision rectangle.
4080* Setting it to positive or negative values will move Link's hitbox left or right.
4081* Writing to this is ignored unless Extend is set to values >=3.
4082* This is not usable, as Link->Extend cannot be set.
4083* While setting it is not syntactically incorrect, it does nothing.
4084* You can read a value that you assign to this (e.g. for custom collision functions).
4085* This value is not preserved through sessions: Loading a saved game will reset it to the default.
4086*
4087*/ Example Use: !#!
4088
4089/************************************************************************************************************/
4090
4091int HitYOffset; ZASM Instruction:
4092 LINKHYOFS
4093
4094/**
4095* The Y offset of Link's hitbox, or collision rectangle.
4096* Setting it to positive or negative values will move Link's hitbox up or down.
4097* Writing to this is ignored unless Extend is set to values >=3.
4098* This is not usable, as Link->Extend cannot be set.
4099* While setting it is not syntactically incorrect, it does nothing.
4100* You can read a value that you assign to this (e.g. for custom collision functions).
4101* This value is not preserved through sessions: Loading a saved game will reset it to the default.
4102*
4103*/ Example Use: !#!
4104
4105/************************************************************************************************************/
4106
4107int DrawXOffset; ZASM Instruction:
4108 LINKXOFS
4109
4110/**
4111* The X offset of Link's sprite.
4112* Setting it to positive or negative values will move the sprite's tiles left or right relative to its position.
4113* Writing to this is ignored unless Extend is set to values >=3.
4114* This is not usable, as Link->Extend cannot be set.
4115* While setting it is not syntactically incorrect, it does nothing.
4116* You can read a value that you assign to this.
4117* This value is not preserved through sessions: Loading a saved game will reset it to the default.
4118*
4119*/ Example Use: !#!
4120
4121/************************************************************************************************************/
4122
4123int DrawYOffset; ZASM Instruction:
4124 LINKYOFS
4125
4126/**
4127* The Y offset of Link's sprite.
4128* Setting it to positive or negative values will move the sprite's tiles up or down relative to its position.
4129* Writing to this is ignored unless Extend is set to values >=3.
4130* This is not usable, as Link->Extend cannot be set.
4131* While setting it is not syntactically incorrect, it does nothing.
4132* You can read a value that you assign to this.
4133* This value is not preserved through sessions: Loading a saved game will reset it to the default.
4134*
4135*/ Example Use: !#!
4136
4137/************************************************************************************************************/
4138
4139int DrawZOffset; ZASM Instruction:
4140 LINKZOFS
4141
4142/**
4143* The Z offset of Link's sprite.
4144* Writing to this is ignored unless Extend is set to values >=3.
4145* The values of DrawZOffset and HitZHeight are linked. Setting one, also sets the other.
4146* This is not usable, as Link->Extend cannot be set.
4147* While setting it is not syntactically incorrect, it does nothing.
4148* You can read a value that you assign to this.
4149* This value is not preserved through sessions: Loading a saved game will reset it to the default.
4150*
4151*/ Example Use: !#!
4152
4153/************************************************************************************************************/
4154
4155float Misc[32]; ZASM Instruction:
4156 LINKMISC
4157 LINKMISCD
4158
4159/**
4160* An array of 32 miscellaneous variables for you to use as you please.
4161* These variables are not saved with Link.
4162*
4163*/ Example Use: !#!
4164
4165/************************************************************************************************************/
4166
4167void Warp(int DMap, int screen); ZASM Instruction:
4168 WARP
4169 WARPR
4170
4171/**
4172* Warps link to the given screen in the given DMap, just like if he'd
4173* triggered an 'Insta-Warp'-type warp.
4174*
4175*/ Example Use: !#!
4176
4177/************************************************************************************************************/
4178
4179void PitWarp(int DMap, int screen); ZASM Instruction:
4180 PITWARP
4181 PITWARPR
4182
4183/**
4184* This is identical to Warp, but Link's X and Y positions are preserved
4185* when he enters the destination screen, rather than being set to the
4186* Warp Return square.
4187*
4188*/ Example Use: !#!
4189
4190/************************************************************************************************************/
4191
4192SelectAWeapon(int dir); ZASM Instruction:
4193 !#!
4194
4195/**
4196* Sets the A button item to the next one in the given direction based on
4197* the indices set in the subscreen. This will skip over items if A and B
4198* would be set to the same item.
4199* If the quest rule "Can Select A-Button Weapon On Subscreen" is disabled,
4200* this function does nothing.
4201*
4202*/ Example Use: !#!
4203
4204/************************************************************************************************************/
4205
4206SelectBWeapon(int dir); ZASM Instruction:
4207 !#!
4208
4209/**
4210* Sets the B button item to the next one in the given direction based on
4211* the indices set in the subscreen. This will skip over items if A and B
4212* would be set to the same item.
4213*
4214*/ Example Use: !#!
4215
4216
4217/************************************************************************************************************/
4218/************************************************************************************************************/
4219
4220
4221//===================================
4222//--- NPC Functions and Variables ---
4223//===================================
4224
4225 class npc
4226
4227
4228 bool isValid(); ZASM Instruction:
4229 ISVALIDNPC
4230 /**
4231 * Returns whether or not this NPC pointer is still valid. A pointer
4232 * becomes invalid if the enemy dies or Link leaves the screen.
4233 * Trying to access any variable of an invalid NPC pointer prints
4234 * an error to allegro.log and does nothing.
4235 */
4236
4237/************************************************************************************************************/
4238
4239 void GetName(int buffer[]); ZASM Instruction:
4240 NPCNAME
4241 /**
4242 * Loads the npc's name into 'buffer'. To load an NPC from an ID rather than a pointer,
4243 * use 'GetNPCName' from std.zh
4244 */
4245
4246/************************************************************************************************************/
4247
4248 int ID; ZASM Instruction:
4249 NPCID
4250 /**
4251 * The NPC's enemy ID number.
4252 * npc->ID is read-only; while setting it is not syntactically incorrect, it does nothing.
4253 */
4254
4255/************************************************************************************************************/
4256
4257 int Type; ZASM Instruction:
4258 NPCTYPE
4259 /**
4260 * The NPC's Type. Use the NPCT_ constants in std.zh to compare this value.
4261 * npc->Type is read-only; while setting it is not syntactically incorrect, it does nothing.
4262 */
4263
4264/************************************************************************************************************/
4265
4266 int X; ZASM Instruction:
4267 NPCX
4268 /**
4269 * The NPC's current X coordinate, in pixels. Float values passed to this will be cast to int.
4270 */
4271
4272/************************************************************************************************************/
4273
4274 int Y; ZASM Instruction:
4275 NPCY
4276 /**
4277 * The NPC's current Y coordinate, in pixels. Float values passed to this will be cast to int.
4278 */
4279
4280/************************************************************************************************************/
4281
4282 int Z; ZASM Instruction:
4283 NPCZ
4284 /**
4285 * The NPC's current Z coordinate, in pixels. Float values passed to this will be cast to int.
4286 */
4287
4288/************************************************************************************************************/
4289
4290 int Jump; ZASM Instruction:
4291 NPCJUMP
4292 /**
4293 * The NPC's upward velocity, in pixels. If negative, the NPC will fall.
4294 * The downward acceleration of Gravity (in Init Data) modifies this value every frame.
4295 */
4296
4297/************************************************************************************************************/
4298
4299 int Dir; ZASM Instruction:
4300 NPCDIR
4301 /**
4302 * The direction the NPC is facing. Use the DIR_ constants in std.zh to
4303 * set and compare this value.
4304 */
4305
4306/************************************************************************************************************/
4307
4308 int Rate; ZASM Instruction:
4309 NPCRATE
4310 /**
4311 * The rate at which the NPC changes direction. For a point of reference,
4312 * the "Octorok (Magic)" enemy has a rate of 16. The effect of writing to
4313 * this field is currently undefined.
4314 */
4315
4316/************************************************************************************************************/
4317
4318 int Haltrate; ZASM Instruction:
4319 NPCHALTRATE
4320 /**
4321 * The extent to which the NPC stands still while moving around the
4322 * screen. As a point of reference, the Zols and Gels have haltrate of
4323 * 16. The effect of writing to this field is currently undefined.
4324 */
4325
4326/************************************************************************************************************/
4327
4328 int Homing; ZASM Instruction:
4329 NPCHOMING
4330 /**
4331 * How likely the NPC is to move towards Link.
4332 * The effect of writing to this field is currently undefined.
4333 */
4334
4335/************************************************************************************************************/
4336
4337 int Hunger; ZASM Instruction:
4338 NPRCHUNGE
4339 /**
4340 * How likely the NPC is to move towards bait.
4341 * The effect of writing to this field is currently undefined.
4342 */
4343
4344/************************************************************************************************************/
4345
4346 int Step; ZASM Instruction:
4347 NPCSTEP
4348 /**
4349 * The NPC's movement speed. A Step of 100 usually means that
4350 * the enemy moves at approximately one pixel per animation frame.
4351 * As a point of reference, the "Octorok (Magic)" enemy has
4352 * a step of 200. The effect of writing to this field is
4353 * currently undefined.
4354 */
4355
4356/************************************************************************************************************/
4357
4358 bool CollDetection; ZASM Instruction:
4359 NPCCOLLDET
4360 /**
4361 * Whether the NPC will use the system's code to work out collisions with Link
4362 * Initialised as 'true'.
4363 */
4364
4365/************************************************************************************************************/
4366
4367 int ASpeed; ZASM Instruction:
4368 NPCFRAMERATE
4369 /**
4370 * The the NPC's animation frame rate, in screen frames. The effect of
4371 * writing to this field is currently undefined.
4372 */
4373
4374/************************************************************************************************************/
4375
4376 int DrawStyle; ZASM Instruction:
4377 NPCDRAWTYPE
4378 /**
4379 * The way the NPC is animated. Use the DS_ constants in std.zh to set or
4380 * compare this value. The effect of writing to this field is currently undefined.
4381 */
4382
4383/************************************************************************************************************/
4384
4385 int HP; ZASM Instruction:
4386 NPCHP
4387 /**
4388 * The NPC's current hitpoints. A weapon with a Power of 1 removes 2
4389 * hitpoints.
4390 */
4391
4392/************************************************************************************************************/
4393
4394 int Damage; ZASM Instruction:
4395 NPCDP
4396 /**
4397 * The amount of damage dealt to an unprotected Link when he touches this NPC, in
4398 * quarter-hearts.
4399 */
4400
4401/************************************************************************************************************/
4402
4403 int WeaponDamage; ZASM Instruction:
4404 NPCWDP
4405 /**
4406 * The amount of damage dealt to an unprotected Link by this NPC's weapon, in
4407 * quarter-hearts.
4408 */
4409
4410/************************************************************************************************************/
4411
4412 int Stun; ZASM Instruction:
4413 NPCSTUN
4414 /**
4415 * The time, in frames, that the NPC will be stunned. Some types of enemies cannot be stunned.
4416 */
4417
4418/************************************************************************************************************/
4419
4420 int OriginalTile; ZASM Instruction:
4421 NPCOTILE
4422 /**
4423 * The number of the starting tile used by this NPC.
4424 */
4425
4426/************************************************************************************************************/
4427
4428 int Tile; ZASM Instruction:
4429 NPCTILE
4430 /**
4431 * The current tile associated with this NPC. The effect of writing to this variable is undefined.
4432 */
4433
4434/************************************************************************************************************/
4435
4436 int Weapon; ZASM Instruction:
4437 NPCWEAPON
4438 /**
4439 * The weapon used by this enemy. Use the WPN_ constants (NOT the EW_ constants)
4440 * in std.zh to set or compare this value.
4441 */
4442
4443/************************************************************************************************************/
4444
4445 int ItemSet; ZASM Instruction:
4446 NPCITEMSET
4447 /**
4448 * The items that the NPC might drop when killed. Use the IS_ constants
4449 * in std.zh to set or compare this value.
4450 */
4451
4452/************************************************************************************************************/
4453
4454 int CSet; ZASM Instruction:
4455 NPCCSET
4456 /**
4457 * The CSet used by this NPC.
4458 */
4459
4460/************************************************************************************************************/
4461
4462 int BossPal; ZASM Instruction:
4463 NPCBOSSPAL
4464 /**
4465 * The boss pallete used by this NPC; this pallete is only used if CSet
4466 * is 14 (the reserved boss cset). Use the BPAL_ constants in std.zh to
4467 * set or compare this value.
4468 */
4469
4470/************************************************************************************************************/
4471
4472 int SFX; ZASM Instruction:
4473 NPCBGSFX
4474 /**
4475 * The sound effects emitted by the enemy. Use the SFX_ constants in
4476 * std.zh to set or compare this value.
4477 */
4478
4479/************************************************************************************************************/
4480
4481 int Extend; ZASM Instruction:
4482 NPCEXTEND
4483 /**
4484 * Whether to extend the sprite of the enemy.
4485 */
4486
4487/************************************************************************************************************/
4488
4489 int TileWidth; ZASM Instruction:
4490 NPCTXSZ
4491 /**
4492 * The number of tile columns composing the sprite.
4493 * Writing to this is ignored unless Extend is set to values >=3.
4494 */
4495
4496/************************************************************************************************************/
4497
4498 int TileHeight; ZASM Instruction:
4499 NPCTYSZ
4500 /**
4501 * The number of tile rows composing the sprite.
4502 * Writing to this is ignored unless Extend is set to values >=3.
4503 */
4504
4505/************************************************************************************************************/
4506
4507 int HitWidth; ZASM Instruction:
4508 NPCHXSZ
4509 /**
4510 * The width of the sprite's hitbox, or collision rectangle.
4511 */
4512
4513/************************************************************************************************************/
4514
4515 int HitHeight; ZASM Instruction:
4516 NPCHYSZ
4517 /**
4518 * The height of the sprite's hitbox, or collision rectangle.
4519 */
4520
4521/************************************************************************************************************/
4522
4523 int HitZHeight; ZASM Instruction:
4524 NPCHZSZ
4525 /**
4526 * The Z-axis height of the sprite's hitbox, or collision rectangle.
4527 * The greater it is, the higher Link must jump or fly over the sprite to avoid taking damage.
4528 * To jump over a sprite, you must be higher than its Z + HitZHeight.
4529 * The values of DrawZOffset and HitZHeight are linked. Setting one, also sets the other.
4530 */
4531
4532/************************************************************************************************************/
4533
4534 int HitXOffset; ZASM Instruction:
4535 NPCHXOFS
4536 /**
4537 * The X offset of the sprite's hitbox, or collision rectangle.
4538 * Setting it to positive or negative values will move the sprite's hitbox left or right.
4539 */
4540
4541/************************************************************************************************************/
4542
4543 int HitYOffset; ZASM Instruction:
4544 NPCHYOFS
4545 /**
4546 * The Y offset of the sprite's hitbox, or collision rectangle.
4547 * Setting it to positive or negative values will move the sprite's hitbox up or down.
4548 */
4549
4550/************************************************************************************************************/
4551
4552 int DrawXOffset; ZASM Instruction:
4553 NPCXOFS
4554 /**
4555 * The X offset of the sprite.
4556 * Setting it to positive or negative values will move the sprite's tiles left or right relative to its position.
4557 */
4558
4559/************************************************************************************************************/
4560
4561 int DrawYOffset; ZASM Instruction:
4562 NPCYOFS
4563 /**
4564 * The Y offset of the sprite. In non-sideview screens, this is usually -2.
4565 * Setting it to positive or negative values will move the sprite's tiles up or down relative to its position.
4566 */
4567
4568/************************************************************************************************************/
4569
4570 int DrawZOffset; ZASM Instruction:
4571 NPCZOFS
4572 /**
4573 * The Z offset of the sprite. This is ignored unless Extend is set to values >=3.
4574 * The values of DrawZOffset and HitZHeight are linked. Setting one, also sets the other.
4575 */
4576
4577/************************************************************************************************************/
4578
4579 int Defense[]; ZASM Instruction:
4580 NPCDEFENSED
4581 /**
4582 * The npc's Defense values, as an array of 18 integers. Use the NPCD_ and NPCDT_ constants
4583 * in std.zh to set or compare these values.
4584 */
4585
4586/************************************************************************************************************/
4587
4588 int ScriptDefense[]; ZASM Instruction:
4589 NPCSCRDEFENSED
4590 /**
4591 * The npc's Script Weapon Defense values, as an array of 10 integers. Use the NPCSD_ and NPCDT_ constants
4592 * in std.zh to set or compare these values.
4593 */
4594
4595/************************************************************************************************************/
4596
4597 int Attributes[]; ZASM Instruction:
4598 NPCDD
4599 /**
4600 * The npc's Miscellaneous Attributes, as an array of ten integers.
4601 * They are read-only; while setting them is not syntactically incorrect, it does nothing.
4602 */
4603
4604/************************************************************************************************************/
4605
4606 int MiscFlags; ZASM Instruction:
4607 NPCMFLAGS
4608 /**
4609 * The npc's Misc. Flags as 14 bits ORed together, starting with 'Damaged by Power 0 Weapons',
4610 * and working down the flags in the order they are shown in the Enemy Editor.
4611 * npc->MiscFlags is read-only; while setting it is not syntactically incorrect, it does nothing.
4612 * If you are not comfortable with binary operations, you can use 'GetNPCMiscFlag' from std.zh
4613 */
4614
4615/************************************************************************************************************/
4616
4617 float Misc[32]; ZASM Instruction:
4618 NPCMISCD
4619 /**
4620 * An array of 32 miscellaneous variables for you to use as you please.
4621 */
4622
4623/************************************************************************************************************/
4624
4625 void BreakShield(); ZASM Instruction:
4626 BREAKSHIELD
4627 /**
4628 * Breaks the enemy's shield if it has one. This works even if the flag
4629 * "Hammer Can Break Shield" is not checked.
4630 */
4631
4632
4633/************************************************************************************************************/
4634/************************************************************************************************************/
4635
4636
4637
4638
4639//======================================
4640//--- Weapon Functions and Variables ---
4641//======================================
4642
4643 class weapon
4644
4645
4646 //! ZScript supports two different weapon classes:
4647 //! The lweapon class is used for Link's weapons (that damage enemies, and trigger objects)
4648 //! while the eweapon class is used for enemy weapons, that can damage Link.
4649 //!
4650 //! Both the lweapon, and the eweapon class have all of the following atributes:
4651
4652 bool isValid(); ZASM Instruction:
4653 ISVALIDLWPN
4654 ISVALIDEWPN
4655
4656 /**
4657 * Returns whether this weapon pointer is still valid. A weapon pointer
4658 * becomes invalid when the weapon fades away or disappears
4659 * or Link leaves the screen. Accessing any variables using an
4660 * invalid weapon pointer prints an error message to allegro.log and
4661 * does nothing.
4662 */ Example Use: !#!
4663
4664/************************************************************************************************************/
4665
4666 void UseSprite(int id); ZASM Instruction:
4667 LWPNUSESPRITER, LWPNUSESPRITEV
4668 EWPNUSESPRITER, EWPNUSESPRITEV
4669
4670 /**
4671 * Reads a 'Weapons/Misc' sprite entry in your quest file, and assigns
4672 * the OriginalTile, Tile, OriginalCSet, CSet, FlashCSet, NumFrames,
4673 * Frame, ASpeed, Flip and Flash variables of this weapon based on
4674 * this entry's data. Passing negative values, and values greater than
4675 * 255, will do nothing.
4676 */ Example Use: !#!
4677
4678/************************************************************************************************************/
4679
4680 bool Behind; ZASM Instruction:
4681 LWPNBEHIND
4682 EWPNBEHIND
4683
4684 /**
4685 * Ensures that the weapon's graphic is drawn behind Link and enemies.
4686 */ Example Use: !#!
4687
4688/************************************************************************************************************/
4689
4690 int ID; ZASM Instruction:
4691 LWPNID
4692 EWPNID
4693
4694 /**
4695 * The weapon's ID number. Use the LW_ or EW_ constants to compare
4696 * this value. The effect of writing to this field is currently undefined.
4697 */ Example Use: !#!
4698
4699/************************************************************************************************************/
4700
4701 int X; ZASM Instruction:
4702 LWPNX
4703 EWPNX
4704
4705 /**
4706 * The weapon's X position on the screen, in pixels. Float values passed
4707 * to this will be cast to int.
4708 */ Example Use: !#!
4709
4710/************************************************************************************************************/
4711
4712 int Y; ZASM Instruction:
4713 LWPNY
4714 EWPNY
4715
4716 /**
4717 * The weapon's Y position on the screen, in pixels. Float values passed
4718 * to this will be cast to int.
4719 */ Example Use: !#!
4720
4721/************************************************************************************************************/
4722
4723 int Z; ZASM Instruction:
4724 LWPNZ
4725 EWPNZ
4726
4727 /**
4728 * The weapon's Z position on the screen, in pixels. Float values passed
4729 * to this will be cast to int.
4730 */ Example Use: !#!
4731
4732/************************************************************************************************************/
4733
4734 int Jump; ZASM Instruction:
4735 LWPNJUMP
4736 EWPNJUMP
4737
4738 /**
4739 * The weapon's falling speed on the screen. Bombs, Bait and
4740 * Fire obey gravity.
4741 */ Example Use: !#!
4742
4743/************************************************************************************************************/
4744
4745 int DrawStyle; ZASM Instruction:
4746 LWPNDRAWTYPE
4747 EWPNDRAWTYPE
4748
4749 /**
4750 * An integer representing how the weapon is to be drawn. Use one of the
4751 * DS_ constants in std.zh to set or compare this value.
4752 */ Example Use: !#!
4753
4754/************************************************************************************************************/
4755
4756 int Dir; ZASM Instruction:
4757 LWPNDIR
4758 eWPNDIR
4759
4760 /**
4761 * The direction that the weapon is facing. Used by certain weapon types
4762 * to determine movement, shield deflection and such.
4763 */ Example Use: !#!
4764
4765/************************************************************************************************************/
4766
4767 int OriginalTile; ZASM Instruction:
4768 LWPNOTILE
4769 EWPNOTILE
4770
4771 /**
4772 * The starting tile of the weapon's animation.
4773 */ Example Use: !#!
4774
4775/************************************************************************************************************/
4776
4777 int Tile; ZASM Instruction:
4778 LWPNTILE
4779 EWPNTILE
4780
4781 /**
4782 * The current tile associated with this weapon.
4783 */ Example Use: !#!
4784
4785/************************************************************************************************************/
4786
4787 int OriginalCSet; ZASM Instruction:
4788 LWPNOCSET
4789 EWPNOCSET
4790
4791 /**
4792 * The starting CSet of the weapon's animation.
4793 */ Example Use: !#!
4794
4795/************************************************************************************************************/
4796
4797 int CSet; ZASM Instruction:
4798 LWPNCSET
4799 EWPNCSET
4800
4801 /**
4802 * This weapon's current CSet.
4803 */ Example Use: !#!
4804
4805/************************************************************************************************************/
4806
4807 int FlashCSet; ZASM Instruction:
4808 LWPNFLASHCSET
4809 EWPNFLASHCSET
4810
4811 /**
4812 * The CSet used during this weapon's flash frames, if this weapon flashes.
4813 */ Example Use: !#!
4814
4815/************************************************************************************************************/
4816
4817 int NumFrames; ZASM Instruction:
4818 LWPNFRAMES
4819 EWPNFRAMES
4820
4821 /**
4822 * The number of frames in this weapon's animation.
4823 */ Example Use: !#!
4824
4825/************************************************************************************************************/
4826
4827 int Frame; ZASM Instruction:
4828 LWPNFRAME
4829 EWPNFRAME
4830
4831 /**
4832 * The weapon's current animation frame.
4833 */ Example Use: !#!
4834
4835/************************************************************************************************************/
4836
4837 int ASpeed; ZASM Instruction:
4838 LWPNASPEED
4839 EWPNASPEED
4840
4841 /**
4842 * The speed at which this weapon animates, in screen frames.
4843 */ Example Use: !#!
4844
4845/************************************************************************************************************/
4846
4847 int Damage; ZASM Instruction:
4848 LWPNPOWER
4849 EWPNPOWER
4850
4851 /**
4852 * The amount of damage that this weapon causes to Link/an enemy upon contact.
4853 */ Example Use: !#!
4854
4855/************************************************************************************************************/
4856
4857 int Step; ZASM Instruction:
4858 LWPNSTEP
4859 EWPNSTEP
4860
4861 /**
4862 * Usually associated with the weapon's velocity. A Step of 100
4863 * typically means that the weapon moves at approximately one pixel
4864 * per animation frame.
4865 */ Example Use: !#!
4866
4867/************************************************************************************************************/
4868
4869 int Angle; ZASM Instruction:
4870 LWPNANGLE
4871 EWPNANGLE
4872
4873 /**
4874 * The weapon's current angle in clockwise radians; used by certain weapon
4875 * types with angular movement. 0 = right, PI/2 = down, etc. Note: if you
4876 * want Link's shield to interact with the weapon correctly, you must set
4877 * its Dir to a direction that approximates this angle.
4878 */ Example Use: !#!
4879
4880/************************************************************************************************************/
4881
4882 bool Angular; ZASM Instruction:
4883 LWPNANGULAR
4884 EWPNANGULAR
4885
4886 /**
4887 * Specifies whether a weapon has angular movement.
4888 */ Example Use: !#!
4889
4890/************************************************************************************************************/
4891
4892 bool CollDetection; ZASM Instruction:
4893 LWPNCOLLDET
4894 EWPNCOLLDET
4895
4896 /**
4897 * Whether the weapon will use the system's code to work out collisions with
4898 * Link and/or enemies (depending on weapon type). Initialised as 'true'.
4899 */ Example Use: !#!
4900
4901/************************************************************************************************************/
4902
4903 int DeadState; ZASM Instruction:
4904 LWPNDEAD
4905 EWPNDEAD
4906
4907 /**
4908 * The current state of the weapon. Important to keep track of. A value of
4909 * -1 indicates that it is active, and moves according to the weapon's
4910 * Dir, Step, Angular, and Angle values. Use -1 if you want the engine to
4911 * handle movement and collision. Use any value below -1 if you want a
4912 * dummy weapon that you can control on your own.
4913 *
4914 * Given a deadstate value of -10, a weapon will turn of its collision
4915 * detection and movement. If it has a positive value, it will
4916 * decrement once per frame until it equals 0, whereupon the weapon is
4917 * removed. If you want to remove the weapon, write one of the WDS_
4918 * constants in std.zh (appropriate for the weapon) to this variable.
4919 *
4920 * Weapons with the type *_SPARKLE have a DeadState equal to the number
4921 * of frames in their sprite animation, when created.
4922 */ Example Use: !#!
4923
4924/************************************************************************************************************/
4925
4926 bool Flash; ZASM Instruction:
4927 LWPNFLASH
4928 EWPNFLASH
4929
4930 /**
4931 * Whether or not the weapon flashes. A flashing weapon alternates between
4932 * its CSet and its FlashCSet.
4933 */ Example Use: !#!
4934
4935/************************************************************************************************************/
4936
4937 int Flip; ZASM Instruction:
4938 LWPNFLIP
4939 EWPNFLIP
4940
4941 /**
4942 * Whether and how the weapon's tiles should be flipped.
4943 * 0: No flip
4944 * 1: Horizontal flip
4945 * 2: Vertical flip
4946 * 3: Both (180 degree rotation)
4947 */ Example Use: !#!
4948
4949/************************************************************************************************************/
4950
4951 int Extend; ZASM Instruction:
4952 LWPNEXTEND
4953 EWPNEXTEND
4954
4955 /**
4956 * Whether to extend the sprite of the weapon.
4957 */ Example Use: !#!
4958
4959/************************************************************************************************************/
4960
4961 int TileWidth; ZASM Instruction:
4962 LWPNTXSZ
4963 EWPNTXSZ
4964
4965 /**
4966 * The number of tile columns composing the sprite.
4967 * Writing to this is ignored unless Extend is set to values >=3.
4968 */ Example Use: !#!
4969
4970/************************************************************************************************************/
4971
4972 int TileHeight; ZASM Instruction:
4973 LWPNTYSZ
4974 EWPNTYSZ
4975
4976 /**
4977 * The number of tile rows composing the sprite.
4978 * Writing to this is ignored unless Extend is set to values >=3.
4979 */ Example Use: !#!
4980
4981/************************************************************************************************************/
4982
4983 int HitWidth; ZASM Instruction:
4984 LWPNHXSZ
4985 EWPNHXSZ
4986
4987 /**
4988 * The width of the sprite's hitbox, or collision rectangle.
4989 */ Example Use: !#!
4990
4991/************************************************************************************************************/
4992
4993 int HitHeight; ZASM Instruction:
4994 LWPNHYSZ
4995 WEPNHYSZ
4996
4997 /**
4998 * The height of the sprite's hitbox, or collision rectangle.
4999 */ Example Use: !#!
5000
5001/************************************************************************************************************/
5002
5003 int HitZHeight; ZASM Instruction:
5004 LWPNHZSZ
5005 EWPNHZSZ
5006
5007 /**
5008 * The Z-axis height of the sprite's hitbox, or collision rectangle.
5009 * The greater it is, the higher Link must jump or fly over the sprite
5010 * To jump over a sprite, you must be higher than its Z + HitZHeight.
5011 * The values of DrawZOffset and HitZHight are linked. Setting one, also sets the other.
5012 * to avoid taking damage.
5013 */ Example Use: !#!
5014
5015/************************************************************************************************************/
5016
5017 int HitXOffset; ZASM Instruction:
5018 LWPNHXOFS
5019 EWPNHXOFS
5020
5021 /**
5022 * The X offset of the sprite's hitbox, or collision rectangle.
5023 * Setting it to positive or negative values will move the sprite's
5024 * hitbox left or right.
5025 */ Example Use: !#!
5026
5027/************************************************************************************************************/
5028
5029 int HitYOffset; ZASM Instruction:
5030 LWPNHYOFS
5031 EWPNHYOFS
5032
5033 /**
5034 * The Y offset of the sprite's hitbox, or collision rectangle.
5035 * Setting it to positive or negative values will move the sprite's
5036 * hitbox up or down.
5037 */ Example Use: !#!
5038
5039/************************************************************************************************************/
5040
5041 int DrawXOffset; ZASM Instruction:
5042 LWPNXOFS
5043 EWPNXOFS
5044
5045 /**
5046 * The X offset of the sprite.
5047 * Setting it to positive or negative values will move the sprite's
5048 * tiles left or right relative to its position.
5049 */ Example Use: !#!
5050
5051/************************************************************************************************************/
5052
5053 int DrawYOffset; ZASM Instruction:
5054 LWPNYOFS
5055 EWPNYOFS
5056
5057 /**
5058 * The Y offset of the sprite.
5059 * Setting it to positive or negative values will move the sprite's
5060 * tiles up or down relative to its position.
5061 */ Example Use: !#!
5062
5063/************************************************************************************************************/
5064
5065 int DrawZOffset; ZASM Instruction:
5066 LWPNZOFS
5067 EWPNZOFS
5068
5069 /**
5070 * The Z offset of the sprite.
5071 * The values of DrawZOffset and HitZHeight are linked. Setting one, also sets the other.
5072 */ Example Use: !#!
5073
5074/************************************************************************************************************/
5075
5076 float Misc[32]; ZASM Instruction:
5077 LWPNMISCD
5078 EWPNMISCD
5079
5080 /**
5081 * An array of 32 miscellaneous variables for you to use as you please.
5082 */ Example Use: !#!
5083
5084
5085/************************************************************************************************************/
5086/************************************************************************************************************/
5087
5088//====================================
5089//--- Item Functions and Variables ---
5090//====================================
5091
5092 class item
5093
5094
5095 bool isValid(); ZASM Instruction:
5096 ISVALIDITEM
5097
5098 /**
5099 * Returns whether this item pointer is still valid. An item pointer
5100 * becomes invalid when Link picks up the item, the item fades away,
5101 * or Link leaves the screen. Accessing any variables using an
5102 * invalid item pointer prints an error message to allegro.log and
5103 * does nothing.
5104 *
5105 */ Example Use: !#!
5106
5107/************************************************************************************************************/
5108
5109 int X; ZASM Instruction:
5110 ITEMX
5111
5112 /**
5113 * The item's X position on the screen, in pixels. Float values passed to this will be cast to int.
5114 *
5115 */ Example Use: !#!
5116
5117/************************************************************************************************************/
5118
5119 int Y; ZASM Instruction:
5120 ITEMY
5121 /**
5122 * The item's Y position on the screen, in pixels. Float values passed to this will be cast to int.
5123 *
5124 */ Example Use: !#!
5125
5126/************************************************************************************************************/
5127
5128 int Jump ZASM Instruction:
5129 ITEMJUMP
5130
5131 /**
5132 * The item's upward velocity, in pixels. If negative, the item will fall.
5133 * The downward acceleration of Gravity (in Init Data) modifies this value every frame.
5134 *
5135 */ Example Use: !#!
5136
5137/************************************************************************************************************/
5138
5139 int DrawStyle; ZASM Instruction:
5140 ITEMDRAWTYPE
5141 /**
5142 * An integer representing how the item is to be drawn. Use one of the
5143 * DS_ constants in std.zh to set or compare this value.
5144 *
5145 */ Example Use: !#!
5146
5147/************************************************************************************************************/
5148
5149 int ID; ZASM Instruction:
5150 ITEMID
5151 /**
5152 * This item's ID number. Use the I_ constants to compare this value. The effect of writing to this field is currently undefined.
5153 *
5154 */ Example Use: !#!
5155
5156/************************************************************************************************************/
5157
5158 int OriginalTile; ZASM Instruction:
5159 ITEMOTILE
5160 /**
5161 * The starting tile of the item's animation.
5162 *
5163 */ Example Use: !#!
5164
5165/************************************************************************************************************/
5166
5167 int Tile; ZASM Instruction:
5168 ITEMTILE
5169 /**
5170 * The current tile associated with this item.
5171 *
5172 */ Example Use: !#!
5173
5174/************************************************************************************************************/
5175
5176 int CSet; ZASM Instruction:
5177 ITEMCSET
5178 /**
5179 * This item's CSet.
5180 *
5181 */ Example Use: !#!
5182
5183/************************************************************************************************************/
5184
5185 int FlashCSet; ZASM Instruction:
5186 ITEMFLASHCSET
5187 /**
5188 * The CSet used during this item's flash frames, if this item flashes.
5189 *
5190 */ Example Use: !#!
5191
5192/************************************************************************************************************/
5193
5194 int NumFrames; ZASM Instruction:
5195 ITEMFRAMES
5196 /**
5197 * The number of frames in this item's animation.
5198 *
5199 */ Example Use: !#!
5200
5201/************************************************************************************************************/
5202
5203 int Frame; ZASM Instruction:
5204 ITEMFRAME
5205 /**
5206 * The tile that is this item's current animation frame.
5207 *
5208 */ Example Use: !#!
5209
5210/************************************************************************************************************/
5211
5212 int ASpeed; ZASM Instruction:
5213 ITEMASPEED
5214 /**
5215 * The speed at which this item animates, in screen frames.
5216 *
5217 */ Example Use: !#!
5218
5219/************************************************************************************************************/
5220
5221 int Delay; ZASM Instruction:
5222 ITEMDELAY
5223 /**
5224 * The amount of time the animation is suspended after the last frame,
5225 * before the animation restarts, in item frames. That is, the total
5226 * number of screen frames of extra wait is Delay*ASpeed.
5227 *
5228 */ Example Use: !#!
5229
5230/************************************************************************************************************/
5231
5232 bool Flash; ZASM Instruction:
5233 ITEMFLASH
5234 /**
5235 * Whether or not the item flashes. A flashing item alternates between
5236 * its CSet and its FlashCSet.
5237 *
5238 */ Example Use: !#!
5239
5240/************************************************************************************************************/
5241
5242 int Flip; ZASM Instruction:
5243 ITEMFLIP
5244
5245 /**
5246 * Whether and how the item's tiles should be flipped.
5247 * 0: No flip
5248 * 1: Horizontal flip
5249 * 2: Vertical flip
5250 * 3: Both (180 degree rotation)
5251 *
5252 */ Example Use: !#!
5253
5254/************************************************************************************************************/
5255
5256 int Pickup; ZASM Instruction:
5257 ITEMPICKUP
5258 /**
5259 * The pickup flags of the item, which determine what happens when Link
5260 * picks up the item. Its value consists of flags OR'd (|) together; use
5261 * the IP_ constants in std.zh to set or compare these values.
5262 * A special note about IP_ENEMYCARRIED: if the Quest Rule "Hide Enemy-
5263 * Carried Items" is set, then an item carried by an enemy will have its
5264 * X and Y values set to -128 while the enemy is carrying it. If this
5265 * flag is removed from such an item, then it will be moved to the enemy's
5266 * on-screen location.
5267 * If you are not comfortable with performing binary operations, use the ItemPickup functions from std.zh.
5268 *
5269 */ Example Use: !#!
5270
5271/************************************************************************************************************/
5272
5273 int Extend; ZASM Instruction:
5274 ITEMEXTEND
5275 /**
5276 * Whether to extend the sprite of the item.
5277 *
5278 */ Example Use: !#!
5279
5280/************************************************************************************************************/
5281
5282 int TileWidth; ZASM Instruction:
5283 !
5284 /**
5285 * The number of tile columns composing the sprite.
5286 * Writing to this is ignored unless Extend is set to values >=3.
5287 *
5288 */ Example Use: !#!
5289
5290/************************************************************************************************************/
5291
5292 int TileHeight; ZASM Instruction:
5293 !
5294 /**
5295 * The number of tile rows composing the sprite.
5296 * Writing to this is ignored unless Extend is set to values >=3.
5297 *
5298 */ Example Use: !#!
5299
5300/************************************************************************************************************/
5301
5302 int HitWidth; ZASM Instruction:
5303 ITEMHSXZ
5304 /**
5305 * The width of the sprite's hitbox, or collision rectangle.
5306 *
5307 */ Example Use: !#!
5308
5309/************************************************************************************************************/
5310
5311 int HitHeight; ZASM Instruction:
5312 ITEMHYSZ
5313 /**
5314 * The height of the sprite's hitbox, or collision rectangle.
5315 *
5316 */ Example Use: !#!
5317
5318/************************************************************************************************************/
5319
5320 int HitZHeight; ZASM Instruction:
5321 ITEMHXSZ
5322 /**
5323 * The Z-axis height of the sprite's hitbox, or collision rectangle.
5324 * The greater it is, the higher Link must jump or fly over the sprite to avoid picking up the item.
5325 * To jump over a sprite, you must be higher than its Z + HitZHeight.
5326 *
5327 */ Example Use: !#!
5328
5329/************************************************************************************************************/
5330
5331 int HitXOffset; ZASM Instruction:
5332 ITEMHXOFS
5333 /**
5334 * The X offset of the sprite's hitbox, or collision rectangle.
5335 * Setting it to positive or negative values will move the sprite's hitbox left or right.
5336 *
5337 */ Example Use: !#!
5338
5339/************************************************************************************************************/
5340
5341 int HitYOffset; ZASM Instruction:
5342 ITEMHYOFS
5343 /**
5344 * The Y offset of the sprite's hitbox, or collision rectangle.
5345 * Setting it to positive or negative values will move the sprite's hitbox up or down.
5346 *
5347 */ Example Use: !#!
5348
5349/************************************************************************************************************/
5350
5351 int DrawXOffset; ZASM Instruction:
5352 ITEMXOFS
5353 /**
5354 * The X offset of the sprite.
5355 * Setting it to positive or negative values will move the sprite's tiles left or right relative to its position.
5356 *
5357 */ Example Use: !#!
5358
5359/************************************************************************************************************/
5360
5361 int DrawYOffset; ZASM Instruction:
5362 ITEMYOFS
5363 /**
5364 * The Y offset of the sprite.
5365 * Setting it to positive or negative values will move the sprite's tiles up or down relative to its position.
5366 *
5367 */ Example Use: !#!
5368
5369/************************************************************************************************************/
5370
5371 int DrawZOffset; ZASM Instruction:
5372 ITEMZOFS
5373 /**
5374 * The Z offset of the sprite.
5375 * The values of DrawZOffset and HitZHeight are linked. Setting one, also sets the other.
5376 *
5377 */ Example Use: !#!
5378
5379/************************************************************************************************************/
5380
5381 float Misc[32]; ZASM Instruction:
5382 ITEMMISCD
5383 /**
5384 * An array of 32 miscellaneous variables for you to use as you please.
5385 * Note that lweapons and eweapons possess exactly the same attributes,
5386 * although their designation affects how they are treated by the engine.
5387 * The values here correspond to both the lweapon and eweapon type.
5388 *
5389 */ Example Use: !#!
5390
5391
5392/************************************************************************************************************/
5393/************************************************************************************************************/
5394
5395
5396//=========================================
5397//--- Itemdata Functions and Variables ---
5398//=========================================
5399
5400 //! You may reference itemdata variables via item scripts, using the 'this' pointer.
5401
5402 class itemdata
5403 int ID; ZASM Instruction:
5404 IDATAID
5405 /**
5406 * Returns the item number of the item in question.
5407 * Can be called with this->ID in item scripts.
5408 */ Example Use: !#!
5409
5410/************************************************************************************************************/
5411
5412 int Modifier; ZASM Instruction:
5413 IDATALTM
5414 /**
5415 * The Link Tile Modifier
5416 *
5417 */ Example Use: !#!
5418
5419/************************************************************************************************************/
5420
5421 int Tile; ZASM Instruction:
5422 IDATATILE
5423 /**
5424 * The tile used by the item.
5425 *
5426 */ Example Use: !#!
5427
5428/************************************************************************************************************/
5429
5430 int CSet; ZASM Instruction:
5431 IDATAID
5432 /**
5433 * The CSet of the tile used by the item.
5434 *
5435 */ Example Use: !#!
5436
5437/************************************************************************************************************/
5438
5439 int Flash; ZASM Instruction:
5440 IDATAFLASH
5441 /**
5442 * The Flash value for the CSet
5443 *
5444 */ Example Use: !#!
5445
5446/************************************************************************************************************/
5447
5448 int AFrames; ZASM Instruction:
5449 IDATAFRAMES
5450 /**
5451 * The number of animation frames in the item's tile animation.
5452 *
5453 */ Example Use: !#!
5454
5455/************************************************************************************************************/
5456
5457 int ASpeed; ZASM Instruction:
5458 IDATAASPEED
5459 /**
5460 * The speed of the item's animation.
5461 *
5462 */ Example Use: !#!
5463
5464/************************************************************************************************************/
5465
5466 int Delay; ZASM Instruction:
5467 IDATADELAY
5468 /**
5469 * The Delay value, before the animation begins.
5470 *
5471 */ Example Use: !#!
5472
5473/************************************************************************************************************/
5474
5475 int Script; ZASM Instruction:
5476 IDATAID
5477 /**
5478 * The Action Script for the item.
5479 *
5480 */ Example Use: !#!
5481
5482/************************************************************************************************************/
5483
5484 int PScript; ZASM Instruction:
5485 IDATAID
5486 /**
5487 * The Pickup Script for the item.
5488 *
5489 */ Example Use: !#!
5490
5491/************************************************************************************************************/
5492
5493 int MagicCost; ZASM Instruction:
5494 IDATAID
5495 /**
5496 * The item's maic (or rupees, if this is set) cost.
5497 *
5498 */ Example Use: !#!
5499
5500/************************************************************************************************************/
5501
5502 int MinHearts; ZASM Instruction:
5503 IDATAID
5504 /**
5505 * The minimum number of hearts required to pick up the item.
5506 *
5507 */ Example Use: !#!
5508
5509/************************************************************************************************************/
5510
5511bool Combine; ZASM Instruction:
5512 IDATACOMBINE
5513 /**
5514 * Corresponds to 'Upgrade when collected twice'.
5515 *
5516 */ Example Use: !#!
5517
5518/************************************************************************************************************/
5519
5520bool Downgrade; ZASM Instruction:
5521 IDATADOWNGRADE
5522 /**
5523 * Corresponds to the 'Remove When Used' option on the Action tab of the item editor.
5524 *
5525 */ Example Use: !#!
5526
5527/************************************************************************************************************/
5528
5529bool KeepOld; ZASM Instruction:
5530 IDATAKEEPOLD
5531 /**
5532 * Corresponds to 'Keep lower level items on the Pickup tab of the item editor.
5533 * NOTE: Not to be confused with 'Keep', which corresponds to the 'Equipment Item' box.
5534 *
5535 */ Example Use: !#!
5536
5537/************************************************************************************************************/
5538
5539bool RupeeCost; ZASM Instruction:
5540 IDATARUPEECOST
5541 /**
5542 * Corresponds to the 'Use Rupees Instead of Magic' option on the item editor 'Action' tab.
5543 *
5544 */ Example Use: !#!
5545
5546/************************************************************************************************************/
5547
5548bool Edible; ZASM Instruction:
5549 IDATAEDIBLE
5550 /**
5551 * Corresponds to the 'Can be Eaten by Enemies' box on the Pickup tab of the item editor.
5552 *
5553 */ Example Use: !#!
5554
5555/************************************************************************************************************/
5556
5557bool GainLower; ZASM Instruction:
5558 IDATAGAINLOWER
5559 /**
5560 * Corresponds to the 'Gain All Lower Level Items' box on the Pickup tab of the item editor.
5561 *
5562 */ Example Use: !#!
5563
5564/************************************************************************************************************/
5565
5566bool Flag1; ZASM Instruction:
5567 IDATAFLAG1
5568 /**
5569 * Multipurpose Flag 1
5570 *
5571 * The properties of this flag change based on the item class (family).
5572 * This corresponds to the box directly below 'Equiment Item'.
5573 * For swords, this is 'B.H. is Percent'.
5574 * Scripted item classes may make use of this as a general-purpose 'Script 1' flag.
5575 * See 'zscript_itemdata.txt' for more information on what this flag does, based on the item class.
5576 *
5577 */ Example Use: !#!
5578
5579/************************************************************************************************************/
5580
5581bool Flag2; ZASM Instruction:
5582 IDATAFLAG2
5583 /**
5584 * Multipurpose Flag 2
5585 *
5586 * The properties of this flag change based on the item class (family).
5587 * This corresponds to the box directly below 'Flag 1, or two boxes down from 'Equiment Item'.
5588 * For swords, this is 'B.D. is Percent'.
5589 * Scripted item classes may make use of this as a general-purpose 'Script 2' flag.
5590 * See 'zscript_itemdata.txt' for more information on what this flag does, based on the item class.
5591 *
5592 */ Example Use: !#!
5593
5594/************************************************************************************************************/
5595
5596bool Flag3; ZASM Instruction:
5597 IDATAFLAG3
5598 /**
5599 * Multipurpose Flag 3
5600 *
5601 * The properties of this flag change based on the item class (family).
5602 * This corresponds to the box directly right of 'Equiment Item'.
5603 * For swords, this is 'B. Penetrates Enemies'.
5604 * Scripted item classes may make use of this as a general-purpose 'Script 3' flag.
5605 * See 'zscript_itemdata.txt' for more information on what this flag does, based on the item class.
5606 *
5607 */ Example Use: !#!
5608
5609/************************************************************************************************************/
5610
5611bool Flag4; ZASM Instruction:
5612 IDATAFLAG4
5613 /**
5614 * Multipurpose Flag 4
5615 *
5616 * The properties of this flag change based on the item class (family).
5617 * This corresponds to the box directly right of 'Flag 2'.
5618 * For swords, this is 'Can Slash'.
5619 * Scripted item classes may make use of this as a general-purpose 'Script 4' flag.
5620 * See 'zscript_itemdata.txt' for more information on what this flag does, based on the item class.
5621 *
5622 */ Example Use: !#!
5623
5624/************************************************************************************************************/
5625
5626bool Flag5; ZASM Instruction:
5627 IDATAFLAG5
5628 /**
5629 * Multipurpose Flag 5
5630 *
5631 * The properties of this flag change based on the item class (family).
5632 * This corresponds to the box directly below 'Flag 4'.
5633 * For swords, this is '<Unused>', and greyed out.
5634 * Scripted item classes may make use of this as a general-purpose 'Script 5' flag.
5635 * See 'zscript_itemdata.txt' for more information on what this flag does, based on the item class.
5636 *
5637 */ Example Use: !#!
5638
5639/************************************************************************************************************/
5640
5641bool Unused; ZASM Instruction:
5642 IDATAFLAGUNUSED
5643 /**
5644 * ? - An extra script-only flag. It's a mystery to everyone.
5645 * Likely best left unused in the event that we need to reserve it.
5646 *
5647 */ Example Use: !#!
5648
5649/************************************************************************************************************/
5650
5651 float InitD[]; ZASM Instruction:
5652 IDATAINITDD
5653 /**
5654 * The original values of the item's 8 'D#' input values are they are stored in the
5655 * .qst file, regardles of whether they have been modified by ZScript.
5656 */ Example Use: !#!
5657
5658/************************************************************************************************************/
5659
5660 void GetName(int buffer[]); ZASM Instruction:
5661 !
5662 /**
5663 * Loads the item this itemdata is attributed to's name into 'buffer'
5664 */ Example Use: !#!
5665
5666/************************************************************************************************************/
5667
5668 int Family; ZASM Instruction:
5669 IDATAFAMILY
5670 /**
5671 * The kind of item to which this class belongs (swords, boomerangs,
5672 * potions, etc.) Use the IC_ constants in std.zh to set or compare this
5673 * value.
5674 */ Example Use: !#!
5675
5676/************************************************************************************************************/
5677
5678 int Level; ZASM Instruction:
5679 IDATALEVEL
5680 /**
5681 * The level of this item. Higher-level items replace lower-level items
5682 * when they are picked up.
5683 */ Example Use: !#!
5684
5685/************************************************************************************************************/
5686
5687 int Power; ZASM Instruction:
5688 IDATAPOWER
5689 /**
5690 * The item's power, for most items this is amount of damage dealt but is
5691 * used for other values in some items (ie. Roc's Feather)
5692 */ Example Use: !#!
5693
5694/************************************************************************************************************/
5695
5696 int Amount; ZASM Instruction:
5697 IDATAAMOUNT
5698 /**
5699 * Corresponds to the "Increase Amount" entry in the Item Editor.
5700 * The value of this data member can have two meanings:
5701 * If Amount & 0x8000 is 1, the drain counter for this item is set
5702 * to Amount & 0x3FFF. The game then slowly fills the counter of this item
5703 * (see Counter below) out of the drain counter. Gaining rupees uses the
5704 * drain counter, for example.
5705 * is set to Amount when the item is picked up.
5706 * If Amount & 0x8000 is 0, the counter of this item is increased, if
5707 * Amount & 0x4000 is 1, or decreased, if Amount & 0x4000 is 0, by
5708 * Amount & 0x3FFF when the item is picked up.
5709 */ Example Use: !#!
5710
5711/************************************************************************************************************/
5712
5713 int Max; ZASM Instruction:
5714 IDATAMAX
5715 /**
5716 * Corresponds to the "Full Max" entry in the Item Editor.
5717 * In conjunction with MaxIncrement (see below) this value controls how
5718 * the maximum value of the counter of this item (see Counter below) is
5719 * modified when the item is picked up. If MaxIncrement is nonzero at that
5720 * time, the counter's new maximum value is at that time set to the
5721 * minimum of its current value plus MaxIncrement, Max.
5722 * If Max is less than the current maximum of the counter, Max is ignored
5723 * and that maximum is used instead.
5724 * Notice that as a special case, if Max = MaxIncrement, the counter's
5725 * maximum value will be forced equal to Max.
5726 */ Example Use: !#!
5727
5728/************************************************************************************************************/
5729
5730 int MaxIncrement; ZASM Instruction:
5731 IDATASETMAX
5732 /**
5733 * Corresponds to the "+Max" entry in the Item Editor.
5734 * In conjunction with Max (see above) this value controls how the
5735 * maximum value of the counter of this item (see Counter below) is
5736 * modified when the item is picked up. If MaxIncrement is nonzero at that
5737 * time, the counter's new maximum value is at that time set to the
5738 * minimum of its current value plus MaxIncrement, and Max.
5739 * If Max is less than the current maximum of the counter, Max is ignored
5740 * and that maximum is used instead.
5741 */ Example Use: !#!
5742
5743/************************************************************************************************************/
5744
5745 bool Keep; ZASM Instruction:
5746 IDATAKEEP
5747 /**
5748 * Corresponds to the "Equipment Item" checkbox in the Item Editor.
5749 * If true, Link will keep the item, and it will show up as an item or
5750 * equipment in the subscreen. If false, it may modify the current value
5751 * or maximum value of its counter (see Counter below), then disappear.
5752 * The White Sword and Raft, for instance, have Keep true, and keys and
5753 * rupees have Keep false.
5754 */ Example Use: !#!
5755
5756/************************************************************************************************************/
5757
5758 int Counter; ZASM Instruction:
5759 IDATACOUNTER
5760 /**
5761 * Corresponds to the "Counter Reference" entry in the Item Editor.
5762 * The game counter whose current and modified values might be modified
5763 * when the item is picked up (see Amount, Max, and MaxIncrement above.)
5764 * Use the CT_ constants in std.zh to set or compare this value.
5765 */ Example Use: !#!
5766
5767/************************************************************************************************************/
5768
5769 int UseSound; ZASM Instruction:
5770 IDATAUSESOUND
5771
5772 /**
5773 * Corresponds to the "Sound" entry on the action tab in the Item Editor.
5774 */ Example Use: !#!
5775
5776
5777/************************************************************************************************************/
5778 int Misc1, Misc2, Misc3, Misc4, Misc5, Misc6, Misc7, Misc8, Misc9, Misc10;
5779 ZASM Instructions:
5780 IDATAMISC1, IDATAMISC2, IDATAMISC3, IDATAMISC4, IDATAMISC5
5781 IDATAMISC6, IDATAMISC7, IDATAMISC8, IDATAMISC9, IDATAMISC10
5782 /**
5783 * These correspond to the pull-down options in the item editor 'Data' tab.
5784 *
5785 * Example: For a Sword Misc1 is 'Beam hearts', and Misc2 is 'Beam .
5786 *
5787 */ Example Use: !#!
5788
5789/************************************************************************************************************/
5790
5791 int Attribute1, Attribute2, Attribute3, Attribute4, Attribute5, Attribute6,
5792 Attribute7, Attribute8, Attribute9, Attribute10;
5793 ZASM Instructions:
5794 IDATAWPN, IDATAWPN2, IDATAWPN3, IDATAWPN4, IDATAWPN5
5795 IDATAWPN6, IDATAWPN7, IDATAWPN8, IDATAWPN9, IDATAWPN10
5796 /**
5797 * These correspond to the pull-down options in the item editor 'Action' tab.
5798 *
5799 * Example: For a Sword Attribute1 is 'Sprite', Attribute 2 is 'Slash sprite'
5800 * and Attribute 3 is 'Beam sprite'.
5801 *
5802 */ Example Use: !#!
5803
5804/************************************************************************************************************/
5805/************************************************************************************************************/
5806
5807
5808//////////////////////
5809/// Array Building ///
5810//////////////////////
5811
5812
5813//////////////////////////////////////
5814/// Poke, or Peek at Memory Values ///
5815/////////////////////////////////////////////////////////////////////////////////////////////////////////
5816/// The following functions are used by ZScript to build arrays, and move data between the registers ///
5817/// that hold them, and generally interpret the values in registers for using arrays. ///
5818/////////////////////////////////////////////////////////////////////////////////////////////////////////
5819/// When an array is declared in ZScript, the following commands are used to create it, ///
5820/// and store its values: ///
5821/// ///
5822/// Creating arrays (global): ///
5823/// ///
5824/// int arr[16]; ///
5825/// int x; ///
5826/// ///
5827/// ZASM Output: ///
5828/// ALLOCATEGMEMV d2,16 : allocates 16 indices to d2 ///
5829/// SETR gd1,d2 : assigns the register d2 to global register gd1 ///
5830/// SETV gd2,0 ///
5831/// ///
5832/////////////////////////////////////////////////////////////////////////////////////////////////////////
5833/// When an array is accessed, and the value of an index read, these instructions: ///
5834/// ///
5835/// int x; ///
5836/// int arr[16]; ///
5837/// x = arr[2]; ///
5838/// ///
5839/// ZASM Output: ///
5840/// ///
5841/// SETV d2,0 : Clear expression axcumulator #1 ///
5842/// PUSHR d3 : Push expression accumulator #2 ///
5843/// SETR d4,SP : Stack frame pointer to stack pointer. ///
5844/// SETR d2,gd1 : Set the value of arr[] to the expression accumulator #1. ///
5845/// PUSHR d2 : Push the expression accumulaor #1 ///
5846/// SETV d2,2 : Store the index we're reading in the expression accumulator #1 ///
5847/// POP d0 : Pop the array index accumulator ///
5848/// SETR d1,d2 : Store the expression accumulator #1 into the secondary array index accumulator. ///
5849/// SETR d2,GLOBALRAM : Read the array values into the expression accumulator #1 ///
5850/// SETR gd2,d2 : Store the value of the inex into x. ///
5851/// SETV d3,0 : Clear the secondary expression accumulator. ///
5852/// ///
5853/////////////////////////////////////////////////////////////////////////////////////////////////////////
5854/// When the values in an array are modified, these instructions: ///
5855/// ///
5856/// arr[2] = 6; ///
5857/// ///
5858/// ZASM Output: ///
5859/// ///
5860/// SETV d2,0 : Clear expression accumulator #1 ///
5861/// PUSHR d3 : Push expression accumulator #2 ///
5862/// SETR d4,SP : Stack frame pointer to stack pointer. ///
5863/// SETV d2,6 : Set expression accumulator #1 to a value of 6 ///
5864/// SETR d0,gd1 : Prep the array index accumulator with the array stored in gd1 ///
5865/// SETR d5,d2 : Sink the value in d2 ///
5866/// PUSHR d0 : Push the array index accumulator. ///
5867/// SETV d2,2 : Store the index to modify in The expression accumulator #1 ///
5868/// POP d0 : Pop off the array index accumulator ///
5869/// SETR d1,d2 : Assign the value of the expression accumulator #1 to the ///
5870/// : secondary array index accumulator. ///
5871/// SETR GLOBALRAM,d5 : Store the value. ///
5872/// SETV d3,0 : Clear the expression accumulaTor #2 ///
5873/////////////////////////////////////////////////////////////////////////////////////////////////////////
5874/// Using these, it would be possible to generate your own array handling routines. ///
5875/////////////////////////////////////////////////////////////////////////////////////////////////////////
5876/// Global arrays are allocated in the REVERSE order of DECLARATION! ///
5877/////////////////////////////////////////////////////////////////////////////////////////////////////////
5878
5879// Peek at RAM value in a global address.
5880
5881void GetGlobalRAM(int register) ZASM Instruction:
5882 GLOBALRAMD
5883Example Use:
5884 Game->GetGlobalRAM(10)
5885 Returns the value in gd10
5886
5887/************************************************************************************************************/
5888
5889// POKE value into Global address
5890
5891void SetGlobalRAM(int register, int value) ZASM Instruction:
5892 GLOBALRAMD<><>
5893Example Use:
5894 Game->SetGlobalRAM(10,6)
5895 Sets gd10 to a value of '6'.
5896
5897/************************************************************************************************************/
5898
5899//Peek at register value of specific script address.
5900void GetScriptRAM(int register) ZASM Instruction:
5901 SCRIPTRAMD<>
5902Example Use:
5903 Game->GetScriptRAM(4)
5904 Returns the value of Script RAM register 4.
5905
5906/************************************************************************************************************/
5907
5908//POKE Vakue into Script RAM address
5909void SetScriptRAM(int register, int value) ZASM Instruction:
5910 SCRIPTRAMD<><>
5911Example Use:
5912 Game->SetScriptRAM(4,12)
5913 Sets script RAM register 4 to a value of '12'
5914
5915/************************************************************************************************************/
5916
5917
5918///////////////////////////////////////
5919/// Misc ZASM-Specific Instructions ///
5920///////////////////////////////////////
5921
5922GOTO<><>
5923GOTOTRUE<><>
5924GOTOFALSE<><>
5925GOTOLESS<><>
5926GOTOMORE<><>
5927POP<>
5928PUSHR<>
5929PUSHV<>
5930ENQUEUER<><>
5931ENQUEUEV<><>
5932DEQUEUE<>
5933GOTOR<>
5934LOADI<><>
5935STOREI<><>
5936LOOP<><>
5937MODR<><>
5938MODV<><>
5939CHECKTRIG
5940COMPOUNDR<>
5941COMPOUNDV<>
5942FLIPROTTILEVV<><>
5943FLIPROTTILERR<><>
5944FLIPROTTILERV<><>
5945FLIPROTTILEVR<><>
5946
5947/* These may not be implemented.
5948 GETTILEPIXELV<>
5949 GETTILEPIXELR<>
5950 SETTILEPIXELV<>
5951 SETTILEPIXELC<>
5952
5953 SHIFTTILEVV<><>
5954 SHIFTTILEVR<><>
5955 SHIFTTILERR<><>
5956 SHIFTTILERV<><>
5957*/
5958
5959
5960/* Handles array data allocation.
5961 ALLOCATEMEMR<><>
5962 ALLOCATEMEMV<><>
5963 ALLOCATEMGEMR<><>
5964 ALLOCATEMGEMV<><>
5965*/
5966
5967/************************************************************************************************************/
5968
5969ZASM Register Reservations
5970
5971Name Register Use
5972SP
5973 stack pointer
5974D4
5975 stack frame pointer
5976D6
5977 stack frame offset accumulator
5978D2
5979 expression accumulator #1
5980D3
5981 expression accumulator #2
5982D0
5983 array index accumulator
5984D1
5985 secondary array index accumulator
5986D5
5987 pure SETR sink
5988
5989
5990//Unimplemented ZASM Instructions
5991GETTILEPIXEL
5992SETTILEPIXEL
5993FLIPROTATETILE
5994SHIFTTILE
5995
5996//partially Implemented ZASM
5997
5998OVERLAYTILE : Supports 8-bit mode tiles only. May support 4-bit only in CSet 0
5999
6000************************************
6001Misc ZASM
6002
6003LOADI LoadIndirect
6004STOREI StoreIndirect
6005
6006
6007////////////////////
6008/// Undocumented ///
6009////////////////////
6010
6011The following are unsupported, and unfinished ZScript functions.
6012 * While calling them is not while setting it is not syntactically incorrect, it does nothing.
6013
6014void SetColorBuffer( int amount, int offset, ZASM Instruction:
6015 int stride, int *ptr ) SETCOLORB
6016
6017Opcode: OSetColorBufferRegister()
6018Example Use:
6019
6020/************************************************************************************************************/
6021
6022void GetColorBuffer( int amount, int offset, ZASM Instruction:
6023 int stride, int *ptr ) GETCOLORB
6024
6025Opcode: OGetColorBufferRegister();
6026Exaple Use:
6027
6028/************************************************************************************************************/
6029
6030void SetDepthBuffer( int amount, int offset, ZASM Instruction:
6031 int stride, int *ptr ) SETDEPTHB
6032
6033Opcode: OSetDepthBufferRegister();
6034Example Use:
6035
6036/************************************************************************************************************/
6037
6038void GetDepthBuffer( int amount, int offset, ZASM Instruction:
6039 int stride, int *ptr ) GETDEPTHB
6040
6041Opcode: OGetDepthBufferRegister();
6042Example use:
6043
6044/************************************************************************************************************/
6045
6046Undocumented / ZASM Exclusive
6047
6048FLOODFILL
6049
6050//////////////////////////////////////////////
6051/// System Limitations, Minimums, Maximums ///
6052//////////////////////////////////////////////
6053
6054 Maximum numeric literal: 214747.9999
6055
6056Ints, Floats, Arrays
6057
6058 Maximum float: -214747.9999 to 214747.9999
6059 Maximum int -214747 to 214747
6060 Maximum array size (number of indices): 214747
6061
6062 * This further includes arrays with a type of npc, leweapon, eweapon, item, and itemdata.
6063 Maximum value in an array index: Same as float, or int; based on type declaration.
6064 Maximum size of string index: 214747
6065 Maximum string length: 214747
6066 Maximum simultaneous arrays in operation: 4095
6067
6068Counters, Tiles, Combos, Strings
6069
6070 Maximum Tiles: 65519
6071 Maximum Combos: 65279
6072 Maximum Counter Value: 0 to 32767
6073 Maximum strings in string editor: ( 65519 )
6074
6075 Largest tile ID (ZQ Editors): 32767 ?
6076
6077 The largest value that can be referenced in the ZQ item, enemy, and other editors.
6078
6079 --> I seem to remember a problem calling high values.
6080
6081Pointers and Objects
6082
6083 Maximum number of item pointers (on-screen items) at any one time: 255
6084 Maximum number of lweapon pointers (on-screen lweapons) at any one time: 255
6085 Maximum number of eweapon pointers (on-screen eweapons) at any one time: 255
6086 Maximum number of npc pointers (on-screen NPCs) at any one time: 255
6087 Maximum number of ffc (on-screen FFCs) pointers at any one time: 32
6088 Array Pointers (maximum number of arrays in operation): 4095
6089
6090 Maximum total (cumulative) number of 'object' pointers at any one time: 1020
6091 * 255 each, npc, lweapon, eweapon, item + 32 (ffcs)
6092
6093 --> ZC separates pointers by class. All pointers are stored in vectors, with pointer IDs ranging from 1 to 255.
6094
6095 Maximum Z Height of a Screen Object (npc, weapon, item) or Link: 32767. Values above this wrap to -32767, which is reset to 0 every frame.
6096
6097Compiler
6098
6099 Maximum constants (any scope): Unlimited. (Constants are converted to their true value at compilation, and are not preserved by name.)
6100 Maximum global variables: 255*
6101 Maximum global functions: 4,294,967,295 (2^32-1).
6102 Note that this is limited by the filesystem, as each function requires its ASCII size in bytes,
6103 and is stored in the quest file. Many filesystems have a file size limit, that restricts it.
6104 At the smallest function size, max functions would use ~40GB of space.
6105 It is further restricted by the maximum buffer size at between 18MB and 22MB.
6106
6107Script Drawing
6108
6109 Maximum number of drawing commands per frame: 1000
6110 Maximum distance (x,y) for drawing, including off-screen areas (and bitmaps): -214747.9999 to 214747.9999 (X and Y)
6111 Maximum Z Height for 3D Drawing: 214747.9999
6112
6113 --> Negative Z Height is effectively '0'.
6114
6115Stack Operation
6116
6117 Maximum number of concurrent stacks: ?
6118 --> Essentially, the maximum number of concurrent scripts; except that item scripts share one stack.
6119
6120 Maximum variables in operation at any given time: 255* (gd1-gd255)
6121 Maximum variables per script: 255*
6122 Maximum function calls per script ( 127* )
6123 *Note: 255 variables will compile, but fail to run. A safe maximum is closer to 245, to allow instructions and function calls on the stack
6124 *Note: Both variables, and function calls share registers (global variables are gd registers), and thus cumulatively count against their combined caps (within a register type). See: ZASM_Registers
6125 --> How are these tabulated at compilation, and is there a strict ratio ( function call:variable ) ?
6126 --> Script-scope variables use gd registers. Thus, you need to retain free registers for scripts to run.
6127
6128 Maximum script buffer size: ~18MB, including code imported with the 'import' directive.
6129 --> Maximum line count is also limited, but it is restricted by being a signed int.
6130 --> Thus, max line-count is somewhere around 2,147,483,647 lines, however,
6131 this is still restricted by the 18MB buffer size.
6132
6133 Maximum number of instructions: 2^32-1 * Max Scripts
6134 Maximum instructions per script: 4,294,967,295 (2^31 - 1)
6135 Maximum instructions per frame: Effectively unlimited, save by instructions per script.
6136
6137 Maximum number of scripts ?
6138 Max ffc scripts at compilation ?
6139 Max Item scripts at compilation ?
6140 Max global scripts at compilation ?
6141 --> I know this is unlikely to ever be reached.
6142
6143 Maximum function calls per script: Limited by maximum instructions, and available gd registers.
6144 Maximum local functions per script: ? Effectively unlimited, and tied to maximum functions (see above).
6145
6146Maximum Values (Binary, Hex) for Use as Flags
6147
6148 The largest literal that you can use as a flag, binary, is: 110100011010111101
6149 ( dec. 214717, hex 0x346BD )
6150
6151 The largest true binary value (all ones) is 11111111111111111
6152 ( dec. 131071, hex 0x1FFFF )
6153
6154 While these are certainly possible, the largest absolutely useful value, that maximises all places in
6155 both binary, and hex, and thus is the true flag maximum is: 65535 (decimal).
6156 This becomes 1111111111111111b, or 0XFFFF, which means that you may use each place to its full potential,
6157 at all times.
6158
6159 Thus, the maximum useful flags are a width of 16-bit, and are represented below.
6160
6161 Max Flag
6162
6163 Binary Hexadecimal Decimal
6164 1111111111111111b 0XFFFF 65535
6165
6166
6167//! A list of all known system limitations.
6168
6169################################
6170## COMPILER ERROR DEFINITIONS ##
6171################################
6172These errors are generated by the parser, during compilation.
6173
6174Error codes are broken down by type:
6175P** Preprocessing errors.
6176S** Symbol table errors.
6177T** Type-checking errors.
6178G** Code Generation Errors
6179** Array Errors ---We need to change these to A**
6180
6181Errors of each class are given unique numerical identifiers, ranging from 00 to 41, such as P01, or G33.
6182The letter code will give you an indication of the type of error, and the full code will give you specific details.
6183
6184In ZQuest v2.50.2 and later, the compiler will report name of the script that generated (where possible).
6185This applies only to errors caused by scripts, and not errors at a 'global' level, such as global functions.
6186Thus, if you are using 2.50.2, or later, an error without a script name is likely to be caused at global scope.
6187
6188#####################
6189## Specific Errors ##
6190## Preprocessing ##
6191#####################
6192
6193P00: Can't open or parse input file!
6194
6195Your script file contains illegal characters, or is not plain ASCII Text.
6196
6197Otherwise, it is possible that the compiler is unable to write to the disk, that the disk is out of space.
6198
6199Last, your file may be bad, such as a file in the qrong encoding format (not ASCII text).
6200
6201P01: Failure to parse imported file foo.
6202
6203Generally means that you are trying to call a file via the import directive that does not exist; or that
6204you have a typo in the filename, or path.
6205
6206
6207P02: Recursion limit of x hit while preprocessing.
6208
6209Caused by attempting to import a file recursively. For example:
6210
6211If you declare: import "script.z" ... and ... the file 'script.z' has the line: ' import "script.z" ' inside it.
6212
6213This error should no longer exist! Recursive imports should resolve as duplicate finction/variable/script declarations.
6214
6215Error P03: You may only place import statements at file scope.
6216
6217Import directives ( import "file.z" ) may only be declared at a global scope, not within
6218a function, statement, or script.
6219
6220P35: There is already a constant with name 'foo' defined.
6221You attempted to define the same constant more than once.
6222The identifier (declared name) of all constants MUST be UNIQUE.
6223
6224
6225#####################
6226## Specific Errors ##
6227## Symbol Table ##
6228#####################
6229
6230S04: Function 'foo' was already declared with that type signature.
6231
6232You attempted to declare a function with the same parameters twice, int he same scope.
6233This can occur when using different types, if the compiler cannot resolve a difference between the signatures.
6234
6235To fix this, remove one function,or change its signature (the arguments inside the parens) so that each is unique or;
6236If you declare a functiona t a global scope, and the same at a local scope, remove one of the two.
6237
6238Note that return type is NOT enough to distinguish otherwise identical function declarations and that 'int' and 'float'
6239types are the same type internally, so int/float is identical insofar as the signature is concerned.
6240
6241If two function type signatures are identical except that one has a parameter of type float where the other has the
6242same parameter of type int, you will have a conflict.
6243
6244There are two additional subtle situations where you might get a conflict:
6245
62461. A function declared at file scope might conflict with a function that's implicitly added to file scope
6247by the preprocessor because of an import statement.
62482. A function might conflict with one already reserved by the ZScript standard library (std.zh).
6249
6250S05: Function parameter 'foo' cannot have void type.
6251
6252You cannot set a parameter (argument of a function) as a void type. e.g.:
6253int foo(void var){ return var+1; }
6254
6255This is illegal, and the param 'var' muct be changed to a legal type.
6256
6257S06: Duplicate script with name 'foo' already exists.
6258
6259Script names must be wholly unique. For example, if there's already an ffc script named 'my_script' you cannot
6260declare an item script with the name 'my_script'.
6261
6262S07: Variable 'foo' can't have type void.
6263
6264Variables at any scope may not have a void type. Only functions may have this type.
6265
6266S08: There is already a variable with name 'foo' defined in this scope.
6267
6268Variable identifiers must be unique at any given scope. Thus, this is illegal:
6269
6270ffc script my_ffc(){
6271 void run(int x){
6272 int v = 1;
6273 int w = 10;
6274 int x = 0.5;
6275 int y = 13;
6276 int z = v+w+x+y;
6277 Trace(z);
6278 }
6279}
6280
6281As the variable 'x' is declared in the params of the run() function, it cannot be declared inside the function with
6282the same identifier (name).
6283
6284
6285S09: Variable 'foo' is undeclared.
6286
6287You attempted to reference a variable identifier (namme) that has not been declared.
6288Usually this is due to a typo:
6289
6290int var;
6291if ( val > 0 ) Link->X += var;
6292
6293Here, 'val' will return this error, as it was not declared.
6294
6295A variable with the give name could not be found in the current or any enclosing scope. Keep in mind the following subtleties:
62961. To access a different script's global variables, or to access a global variable from within a function delcared at file scope,
6297you must use the dot operator: scriptname.varname.
62982. To access the data members of the ffc or item associated with a script, you must use the this pointer: this->varname.
62993. ZScript uses C++-style for loop scoping rules, so variables declared in the header part of the for loop cannot be
6300accessed outside the loop:
6301
6302Code:
6303
6304for(int i=0; i<5;i++);
6305i = 2; //NOT legal
6306
6307S10: Function 'foo' is undeclared.
6308
6309You attempted to call a function that was not declared. This is usually due to either a typo in your code, or failing
6310to import a mandatory header. Check that you are importing 'std.zh' as well, as failing to do this will result in a slew
6311of this error type.
6312
6313S11: Script 'foo' must implement void run().
6314
6315Every script must implement run() function call. The signature may be empty, or contain arguments.
6316Zelda Classic uses all the code inside the run() function when executing the script, so a script without
6317this function would do nothing, and will return an error.
6318
6319S12: Script 'foo's' run() must have return type void.
6320
6321Is this error even implemented? The run() function is automatic, and never declared by type, unless the user tries to declare
6322a separate run(params) function with a different type.
6323
6324S26: Pointer types (ffc, etc) cannot be declared as global variables.
6325
6326/* It is illegal to declare a global variable (that is, a variable in script scope) or any type other than int, float, and bool.
6327Why? Recall that global variables are permanent; they persist from frame to frame, screen to screen.
6328Pointer types, on the other hand, reference ffcs or items that are transitory; they become stale after a single WAITFRAME,
6329so it makes no sense to try to store them for the long term.
6330*/
6331
6332This explanation may no longer be true, as pointers may no longer be dereferenced by Waitframe(),
6333and global pointers may also be implemented in a future version.
6334
6335
6336S30: Script foo may have only one run method.
6337
6338You may not call a run() function more than once per script.
6339Your run method may have any type signature, but because of this flexibility, the compiler cannot
6340determine which run script it the "real" entry point of the script if multiple run methods are declared.
6341
6342S32: Script foo is of illegal type.
6343
6344The only legal script tokens are: global, ffc, and item. You cannot declare other types (such as itemdata script).
6345
6346S38: Script-scope global variable declaration syntax is deprecated; put declarations at file scope instead.
6347You cannot declare a global variable in a global script, outside the run function.
6348
6349Example:
6350
6351global script active{
6352 int x;
6353 void run(){
6354 x = 16;
6355 }
6356}
6357
6358This is ILLEGAL. The declaration of variable 'x' must either be at a global scope, or at the scope of the
6359run function. Do this, instead:
6360
6361int x;
6362global script active{
6363 void run(){
6364 x = 16;
6365 }
6366}
6367
6368This creates a global variable at the file scope.
6369
6370S39: Array 'foo' can't have type void.
6371Arrays may be types of int, float, bool, ffc, item, itemdata, npc, lweapon, or eweapon; but arrays
6372with a void type are illegal.
6373
6374S40: Pointer types (ffc, etc) cannot be declared as global arrays.
6375As of 2.50.2, global array declarations may only have the following types:
6376int, float, bool
6377Any other type is illegal.
6378
6379S41: There is already an array with name 'foo' defined in this scope.
6380As with variables, and functions, arrays must have unique identifiers within the same scope.
6381
6382###################
6383## LEXING ERRORS ##
6384###################
6385L24: Too many global variables.
6386
6387The assembly language to which ZScript is compiled has a built-in maximum of 256 global variables. ZScript can't do anything if you exceed this limit.
6388
6389#####################
6390## Specific Errors ##
6391## Type Checking ##
6392#####################
6393
6394T13: Script 'foo' has id that's not an integer.
6395
6396/* I do not know what can cause this error, or if it ever occurs. */
6397
6398T14: Script 'foo's' id must be between 0 and 255.
6399
6400Occurs if you try to load more than 256 scripts of any given type at any given time.
6401/* The maximum number of concurrent scripts (of any given type?) is 256. */
6402
6403T15: Script 'foo's' id is already in use.
6404You attempted to laod two scripts into the same slot.
6405/* I do not know if this is EVER possible. */
6406
6407T16: Cast from foo to bar.
6408
6409The only "safe" implicit casts are from int to float and vice-versa (since they are the same type),
6410and from int (or float) to bool (0 becomes false, anything else true).
6411The results of any other kind of cast are unspecified.
6412
6413/*
6414Is this error still in effect? Casting from npc to itemdata, or others, usually results in a different error code.
6415Further, Cannot cast from wtf to int, is a thing.
6416*/
6417
6418Explicit casts are unimplemented and unnecessary.
6419
6420T17: Cannot cast from foo to bar.
6421
6422You attempted to typecast illegally, such as tyring to typecast from bool to float.
6423
6424T18: Operand is void.
6425Occurs if you try to use a void type value in an operation.
6426/* I do not know if this is EVER possible. */
6427
6428T19: Constant division by zero.
6429
6430While constant-folding, the compiler has detected a division by zero
6431
6432 Example:
6433 const int MY_CONSTANT = 0;
6434 ffc script foo{
6435 void run(){
6436 int x = 6;
6437 Link->Jump = x / MY_CONSTANT;
6438 }
6439 }
6440
6441Correct the value of your constant. Perhaps you meant to use a variable?
6442
6443Note that only division by a CONSTANT zero can be detected at compile time.
6444The following code, for instance, compiles with no errors but will generate script errors during execution.
6445
6446 Example:
6447
6448 int x = 0;
6449 int y;
6450 y = 1/x;
6451
6452
6453
6454
6455T20: Truncation of constant x.
6456
6457Constants can only be specified to four places of decimal precision, withing the legal range of values.
6458Any extra digits are simply ignored by the compiler, which then issues this warning.
6459
6460Any values greater than MAX_CONSTANT, or less then MIN_CONSTANT will result in this error.
6461
6462## Applies to variables, but does not throw an error:
6463Both floats and ints can only be specified to four places of decimal precision.
6464Any extra digits are simply ignored by the compiler, which then issues this warning.
6465
6466Any values greater than MAX_VARIABLE, or less then MIN_VARIABLE will result in this error.
6467
6468########
6469
6470T21: Could not match type signature 'foo'.
6471
6472When calling a function, you used the wrong number, or types, of parameters.
6473The compiler can determine no way of casting the parameters of a function call so that they
6474match the type signature of a declared function.
6475
6476For instance, in the following snippet
6477Code:
6478
6479int x = Sin(true);
6480
6481since true cannot be cast to a float, this function call cannot be matched to the library function Sin, triggering this error.
6482
6483
6484T22: Two or more functions match type signature 'foo'.
6485
6486If there is ambiguity as to which function declaration a function call should matched to,
6487the compiler will attempt to determine the "best fit."
6488These measures are however occasionally still not enough. Consider for instance the following snippet:
6489Code:
6490
6491void foo(int x, bool y) {}
6492void foo(bool x, int y) {}
6493foo(1,1);
6494
6495matching either of the two foo declarations requires one cast, so no match can be made.
6496In contrast, the following code has no error:
6497Code:
6498
6499void foo(int x, bool y) {}
6500void foo(bool x, bool y) {}
6501foo(1,1);
6502
6503(The first foo function is matched.)
6504
6505It is best to design functions so that noambiguity is possible, by addign extra params, to change the signature or by using
6506different identifiers (function names) when using more params is not desirable.
6507
6508T23: This function must return a value.
6509
6510All return statements must be followed by an expression if the enclosing function returns a value.
6511Note that the compiler does NOT attempt to verify that all executions paths of a function with non-void
6512return type actually returns a value; if you fail to return a value, the return value is undefined.
6513For instace, the following is a legal (though incorrect) ZScript program:
6514
6515int foo() {}
6516
6517/* I don't believe anythign ever returns this error.
6518I've seen functions with int/float/bool types, and no returns compile, without errors.
6519Perhaps we should fix this, and issue a warning during compilation? */
6520
6521T25: Constant bitshift by noninteger amount; truncating to nearest integer.
6522
6523The bitshift operators (<< and >>) require that their second parameters be whole integers.
6524
6525T27: Left of the arrow (->) operator must be a pointer type (ffc, etc).
6526
6527It makes no sense to write "x->foo" if x is of type int.
6528You may only use the dereference (->) operator on pointer types.
6529
6530T28: That pointer type does not have a function 'foo'.
6531
6532You tried to use the dereference operator (->) to call a function that does not exist for the pointer type being dereferenced.
6533Check the list of member variables and functions and verify you have not mistyped the function you are trying to call.
6534
6535This generally occurs when calling internal functions, using the incorrect class, or namespace, such as:
6536
6537Game->Rectangle() instead of Screen->Rectangle()
6538
6539The extra std.zh component 'shortcuts.zh' assists in preventing this error type.
6540
6541
6542T29: That pointer type does not have a variable 'foo'.
6543
6544You tried to use the dereference operator (->) to call a member variable that does not exist for the pointer type being dereferenced.
6545Check the list of member variables and verify you have not mistyped the variable you are trying to call.
6546
6547This generally occurs when calling internal variables, using the incorrect class, or namespace, such as:
6548
6549Link->D[] instead of Screen->D[]
6550
6551/* The extra std.zh component 'shortcuts.zh' assists in preventing this error type.
6552Probaby not, as this requires silly amounts of functions to handle variables with identical identifiers.
6553C'est la vie. perhaps we'll do it, but I really am not fond of the idea. */
6554
6555As above, but the member variable you tried to access does not exist.
6556
6557Error T31: The index of 'foo' must be an integer.
6558
6559/* This has been deprecated, so who cares? */
6560
6561
6562T36: Cannot change the value of constant variable 'foo'.
6563
6564You cannot assign a CONSTANT to another value.
6565
6566T37: Global variables can only be initialized to constants or globals declared in the same script.
6567You cannot (directly) simultaneously declare, and initialise a global value using the value of a variable at
6568the scope of another script, or function.
6569
6570Example:
6571int x = script.a;
6572ffc script foo{
6573 int a = 6;
6574 void run(){
6575 for ( int q = 9; q < Rand(15); q++ ) a++;
6576 }
6577}
6578
6579This is ILLEGAL. You cannot initialise the value of the global variable 'x' using the local value
6580of 'a' in the ffc script 'foo'.
6581
6582/* I believe this is deprecated, as I do not believe that script level declarations remain legal */
6583
6584T45 (old version, T38): Arrays can only be initialized to numerical values
6585You attempted to declare an array using a floating point value (e.g. 10.5), constant or equation,
6586rather than a numeric literal.
6587
6588
6589 Consider that you want to declare an array with an explicit size of '40':
6590 These are ILLEGAL:
6591 int my_arr[26+14];
6592 const int CONSTANT = 30;
6593 int my_arr[CONSTANT];
6594 int my_arr[CONSTANT/2+20]
6595
6596 YOu must declare an arrray with a numeric literal:
6597 int my_array[40];
6598 This is the only legal way to declare the size of an array as of 2.50.2.
6599
6600
6601#####################
6602## Specific Errors ##
6603## @Generation ##
6604#####################
6605
6606
6607G33: Break must lie inside of an enclosing for or while loop.
6608
6609The 'break' keyword aborts the loop (in a for, while, or do statement) in which it is called.
6610You must be in a loop to break out of one, so calling 'break' outside of a loop is illegal.
6611
6612
6613G34: Continue must lie inside of an enclosing for or while loop.
6614
6615The 'continue' keyword halts a loop, and repeats the loop from its head (in a for, while, or do statement) in which it is called.
6616You must be in a loop to continue one, so calling 'continue' outside of a loop is illegal.
6617
6618As the above error, but with the continue keyword. Continue aborts the current iteration of the loop and skips to the next iteration.
6619
6620
6621##################
6622## Array Errors ##
6623##################
6624
6625Error A42 (old, Error O1): Array is too small. ( Converting to A42 in 2.50.3 )
6626You attempted to declare an array, with a set of values, where the number of values in the set
6627exceeds an explicit array size declaration:
6628
6629int foo[4]={1,2,3,4,5};
6630The declared size is '4', but you tried to initialise it with five elements.
6631
6632/* THis doesn't seem right, as this seems to be covered by Err 02. Check the source to see what causes this. */
6633
6634Error O2: Array initializer larger than specified dimensions. ( Converting to A43 in 2.50.3)
6635You attempted to initialise an array, with a set of values, where the number of values in the set
6636exceeds an explicit array size declaration:
6637
6638int foo[4]={1,2,3,4,5};
6639The declared size is '4', but you tried to initialise it with five elements.
6640
6641Error O3: String array initializer larger than specified dimensions, space must be allocated for NULL terminator.
6642( Convering to A44 in 2.50.3 )
6643YOu attempted to seclare a QUOTEDSTRING of an explicit size, but you didn;t add space
6644for the NULL terminator; or you used more chars than you allocated:
6645
6646int my_string[17]="This is a string.";
6647 THis allocates only enough indices for the chars, but not for the NULL terminator.
6648 The array size here needs to be 18.
6649int my_string[12]="THis is a string.";
6650 You tried to initialise a QUOTEDSTRING that is longer than the array size.
6651 The minimum array size for this is '18'.
6652
6653 It is generally best either to declare strings with an implicit size (set by the initialiser):
6654 int my_string[]="This is a string";
6655 This reads the nuber of chars, adds one to the count (for NULL), and sizes the array to 18.
6656 ...or...
6657 Declare the string with an arbitrarily large size:
6658 int my_string[256]="This is a string";
6659 This reserves 256 chars. Only 18 are used, and the rest of the indices
6660 are initialised as '0' (NULL). YOu may later populate the unused space, if desired.
6661
6662
6663#################
6664## Misc Errors ##
6665#################
6666
6667FATAL FATAL ERROR I0: bad internal error code
6668A fallback error if no other type matches the problem.
6669
6670/* I have no idea what causes this. Be afraid, very afraid. */
6671
6672/* OTHER ERRORS
6673Document any further error codes here.
6674We need to convert the array errors from raw numeric, to A** codes.
6675*/
6676
6677########################
6678## OPERATIONAL ERRORS ##
6679###################################################################################################
6680## These errors occur only during the operation of script execution (i.e. when running a script, ##
6681## in Zelda Classic while playing a quest). ##
6682## --------------------------------------------------------------------------------------------- ##
6683## In ZC versions 2.50.2, and later, operational script errors will return the ID of the script ##
6684## from which they were generated. ##
6685###################################################################################################
6686
6687//! These errors will be reported to allegro.log (or the ZConsole) when scripts run.
6688
6689
6690
6691////////////////////
6692/// Stack Errors ///
6693////////////////////
6694
6695 "Stack over or underflow, stack pointer = %ld\n"
6696
6697* !? How should I describe this, and give examples?
6698
6699 "Invalid ZASM command %ld reached\n"
6700
6701Stack instruction countber reached, or exceeded. The stack counter is an unsigned int, so it's maximum value is 65536.
6702You have isused more instructiosn this frame than the instructon counter can ahndle. Look through your code for
6703something that may be doing this.
6704
6705////////////////////
6706/// Array Errors ///
6707////////////////////
6708
6709 "Invalid value (%i) passed to '%s'\n"
6710 "Invalid index (%ld) to local array of size %ld\n"
6711
6712You attempted to reference an array index that is either too small, or too large.
6713Check the size of your array, and try again.
6714Perhaps you have a for loop, or other loop that is parsing the array, and trying to read beyond its index ranges.
6715
6716
6717 "Invalid pointer (%i) passed to array (don't change the values of your array pointers)\n"
6718
6719Array pointers values in operation are 1 through 4095, ( and 4096 to 8164? as declared global pointers ?).
6720An array may not have a pointer of '0', nor may you reference an array for which a pointer does not exist.
6721Often, this error is caused by attempting to reference an array that you created, without updating the saved game slot
6722as the old save does not have the array allocated, but the script is attempting to reference its global ID.
6723
6724 "Script tried to deallocate memory at invalid address %ld\n"
6725 "Script tried to deallocate memory that was not allocated at address %ld\n"
6726
6727/* Script attempted to change the value of an array index // that does not exist // due to the inability to declare an array
6728because too many registers are in use?
6729
6730
6731 "You were trying to reference an out-of-bounds array index for a screen's D[] array (%ld); valid indices are from 0 to 7.\n"
6732You attempted to read, or write to a Screen->D[register] that was less than 1, or greater than 10.
6733Check for loops, and vriables that read/write to Screen->D for any that can fall outside the legal range.
6734
6735 "Array initialized to invalid size of %d\n"
6736You attempted to init array to a size less than 1, or a size greater than 214747, or;
6737You attempted to init array with a constant, a variable, a formula, or with a floating point value.
6738Arrays may ONLY be initialised with numeric literals (integers only) between 1 and 214747.
6739
6740 "%d local arrays already in use, no more can be allocated\n", MAX_ZCARRAY_SIZE-1);
6741The maximum number of arrays in operation at one time is 4095.
6742
6743"Invalid pointer value of %ld passed to global allocate\n"
6744 !
6745
6746/////////////////////////////
6747/// Object Pointer Errors ///
6748/////////////////////////////
6749
6750 "Invalid NPC with UID %ld passed to %s\nNPCs on screen have UIDs "
6751 "Invalid item with UID %ld passed to %s\nItems on screen have UIDs "
6752 "Invalid lweapon with UID %ld passed to %s\nLWeapons on screen have UIDs "
6753 "Invalid eweapon with UID %ld passed to %s\nEWeapons on screen have UIDs "
6754
6755 "Script attempted to reference a nonexistent NPC!\n"
6756 "You were trying to reference the %s of an NPC with UID = %ld; NPC on screen are UIDs "
6757
6758 "Script attempted to reference a nonexistent item!\n"
6759 "You were trying to reference an item with UID = %ld; Items on screen are UIDs: "
6760
6761 "Script attempted to reference a nonexistent LWeapon!\n"
6762 "You were trying to reference the %s of an LWeapon with UID = %ld; LWeapons on screen are UIDs "
6763
6764 "Script attempted to reference a nonexistent EWeapon!\n"
6765 "You were trying to reference the %s of an EWeapon with UID = %ld; EWeapons on screen are UIDs "
6766
6767You attempted to reference a game object that has a maximum legal range of 1 to 255.
6768It is possible that you tried to read outside that range, or that the pointer that you were loading is not valid.
6769Check NumItems(), NumLWeapons(), NumEWeapons(0, and NumNPCs() before referencing them; and verify that the object ->IsValid()
6770Check for loops that may attempt ro reference items outside of the range that actually exist.
6771Look for any for loops that access these objects, that start, or end at zero.
6772
6773The best way to ensure this does not occur, is to make a for loop as follows:
6774
6775 for ( int q = 1; q < Screen->NumLWeapons; q++ )
6776
6777 //or//
6778
6779 for ( int q = Screen->NumLWeapons(); q > 0; q-- )
6780
6781...replacing NumLWeapons() withthe appropriate type that you are attempting to load.
6782
6783You may be attempting to refrence a pointer that has fallen out of scope.
6784You may be attempting to reference a pointer that is no longer valid, or has been removed.
6785Check ( pinter->IsValid() ) by itself, to ensure this does not occur:
6786
6787 if ( pointer->IsValid ) {
6788 if ( pointer->ID == LW_FIRE ) //Do things.
6789 }
6790
6791This helps to prevent loading invalid pointers.
6792
6793////////////////////////////////
6794/// Maths and Logical Errors ///
6795////////////////////////////////
6796
6797"Script attempted to divide %ld by zero!\n"
6798"Script attempted to modulo %ld by zero!\n"
6799
6800"Script attempted to pass %ld into ArcSin!\n"
6801"Script attempted to pass %ld into ArcCos!\n"
6802"Script tried to calculate log of 0\n"
6803"Script tried to calculate log of %f\n"
6804"Script tried to calculate ln of 0\n"
6805"Script tried to calculate ln of %f\n"
6806"Script attempted to calculate 0 to the power 0!\n"
6807"Script attempted to calculate square root of %ld!\n"
6808
6809Look for scripts that pass a variable into these functions, or use a variable in a mathematical operation, that
6810may be zero at any point, and correct it to ensure that it is never zero, or that it is never illegal for the type of
6811mathematical operation you wish to perform.
6812
6813Chweck for any hardcoded values, or constants that are in use with these functions that may be illegal, or irrational.
6814
6815////////////////////////////////
6816/// System Limitation Errors ///
6817////////////////////////////////
6818
6819"Couldn't create lweapon %ld, screen lweapon limit reached\n"
6820"Couldn't create eweapon %ld, screen eweapon limit reached\n"
6821"Couldn't create item \"%s\", screen item limit reached\n"
6822"Couldn't create NPC \"%s\", screen NPC limit reached\n"
6823
6824You may create a maximum of 255 of any one object type on the screen at any one time.
6825Look for anything that is generating extra pointers, and add a statement such as:
6826 if ( Screen->NumNPCs() < 255 )
6827
6828 "Max draw primitive limit reached\n"
6829The maximum number of drawing function calls, per frame, is 1,000.
6830
6831/////////////////////
6832/// String Errors ///
6833/////////////////////
6834
6835 "Array supplied to 'Game->GetDMapMusicFilename' not large enough\n"
6836 "Array supplied to 'Game->GetSaveName' not large enough\n"
6837 "String supplied to 'Game->GetSaveName' too large\n"
6838 "Array supplied to 'Game->GetMessage' not large enough\n"
6839 "Array supplied to 'Game->GetDMapName' not large enough\n"
6840 "Array supplied to 'Game->GetDMapTitle' not large enough\n"
6841 "Array supplied to 'Game->GetDMapIntro' not large enough\n"
6842 "Array supplied to 'itemdata->GetName' not large enough\n"
6843 "Array supplied to 'npc->GetName' not large enough\n"
6844
6845The buffer for these actions must be equal to the size of the text to load into it, plus one, for NULL.
6846
6847If you wish to load a game name, with Game->LoadSaveName(), and the name on the file select is FOO, you must
6848supply a buffer with a size of [4] to hold it. (Three chars in the name, plus one for NULL.)
6849
6850////////////////////
6851/// Misc. Errors ///
6852////////////////////
6853
6854 "Waitdraw can only be used in the active global script\n"
6855You attempted to call Waitdrw() in an ffc script, or an item script; or in your global OnContinue,
6856global OnExit, or ~Init scripts.
6857You may only use the Waitdraw() function from a global active script.
6858
6859 "No other scripts are currently supported\n"
6860? You should never see this. May indicate that you have attempted to load more scripts than ZC can handle.
6861
6862
6863 "Invalid value (%i) passed to '%s'\n"
6864!? WHat should we put here?
6865
6866 "Global scripts currently have no A registers\n"
6867This error can only occur if you are coding ZASM, and attempt to utilise an Address register with a global script.
6868
6869////////////////////////
6870/// Script Reporting ///
6871////////////////////////
6872
6873 //Events that will be recorded if Quest Rule 'Log Game Events to Allegro.log' is enabled:
6874
6875"Script created lweapon %ld with UID = %ld\n"
6876"Script created eweapon %ld with UID = %ld\n"
6877"Script created item \"%s\" with UID = %ld\n"
6878"Script created NPC \"%s\" with UID = %ld\n"
6879
6880When any new game object is generated by script, and reporting is enabled, the lweapon, and the name of the
6881script that generated it, will be reported to allegro.log.
6882
6883
6884///////////////////////////
6885/// Documentation Staff ///
6886///////////////////////////
6887
6888ZScript documentation generated, and maintained by:
6889DarkDragon (retired)
6890Gleeok
6891Saffith
6892ZoriaRPG