FAQ / FOIRE AUX QUESTIONS

Why did you make AOZ Studio?


We started using computers in the '80s, a time when we as kids or grown-ups had the fantastic chance to learn by ourselves thanks to the natural and easy BASIC language. We created software, games, utilities, demos, and in the process had to understand the computers's architecture.

Many of us became programmers, founders or managers in small or big hi-tech companies.

Today, we all are dependent on the various forms of computers and phones we use most of the day. To make a long story short, trans-humanism, artificial intelligence, and robotics are opportunities, but only if we can control them. Otherwise, they and their makers take control.

Our kids, the new generation, our future, are not in control. They use computers many hours per day, and yet only a fraction of them can program or even begin to understand how it works.

Why? First of all, because installing a development tool nowadays, discovering the sophisticated language and learning to use it, implies mastering complex concepts. Windows, accolades, objects, coordinates, inputs, outputs, display, frames, so many other new things must be grasped at the same time! It can take up to several days to print a simple "Hello world".

With the initial hurdle set so high, most abandon it after a couple of days, thinking "I will never be a programmer. Computers are too complex.".

Despite the fact that there are great tools to learn the logic of programming, Scratch, Codecombat, to name a few, they are not powerful enough to create real applications, and more importantly, they miss the link between learning and producing publishable professional software.

We created AOZ Studio with a mission: to help us all take control, understand, and learn, and eventually to find a job in the software industry.

- If you know nothing about programming and want to publish the app, game or website of your dreams, you have come to the right place.

- Do you have an excellent idea for a game and want to sell it? Welcome to AOZ Studio!

Our goal is that everyone can start from scratch. We want you to create your first bug-free program in under five minutes. After such a start, you will be motivated to follow an accessible path of self-teaching, with a smooth learning curve, and instant gratifying results. You will be able to create, publish and share your creations online in a click!

We know that the path is long and that we have a lot of work ahead of us, yet with such a mission, we are very motivated and will dedicate ourselves fully until we reach our goal: To create the most straightforward and most powerful tool for both education and production, AOZ Studio.

Please be patient, we still have a lot of work ahead of us...

Thank you and we hope you will enjoy this community of AOZ creators.

Francois, Laurant and Baptiste.




How do you pronounce AOZ?


We decided on this name thinking about the movie “The Wizard of OZ”.
We want you to become the “The Wizards of AOZ”.

Wizards do not need advice on how to pronounce their magic spells. Be creative, and find your way to say the name. In French, we say “aoze”, with the typical French “a” and the silent “e” at the end.

The international phonetic representation is... aoz. ;)




What's the difference between AOZ and AOZ Studio?


AOZ is the name of the language. AOZ Studio is both the name of the company and the set of tools we use to build the language (the IDE).




I have never programmed.  Can I make a program with AOZ?


YES! It will become easier and easier thanks to the AOZ community, tutorials, examples, and the new features we are building.




Can you really make good games with AOZ studio?


YES! Please see examples like Cybenet, CyBlock and others on YouTube: https://www.youtube.com/channel/UCgNZMa2njTO5ddNGdN9obWg , and many others included with the AOZ Studio package in the Applications folder.

We are originally gamers with a long experience in the video game industry. Some of us founded leading video game companies.

The executable code generated by AOZ Studio is an optimized JavaScript that you can run on most platforms and interface with. It is a very open world.

We are building a sprite/graphic editor especially for games (expected in Q2 2021)

We are adding innovative 3D and sound features etc. Stay tuned...




Why the BASIC language?


We're using BASIC for several reasons:

1. BASIC is by definition, a language that is easy to lean and use for beginners. (BASIC is an acronym for Beginners' All-purpose, Symbolic Instruction Code.)

2. Not only is it easy to use, but AOZ is also very powerful, making complex graphics, animation, and audio capabilities available, accessible, and easy to code for users of all levels.

3. It saves time! What might take weeks or months to create in languages like C or Java may take only hours or days when using AOZ!




The current version is in beta.  When do you plan to release the real one?


We are planning on releasing V1 at year end of 2020. In the meantime, you can use Beta version, and create great apps with it!




What is the difference between AOZ and educational tools like Scracth?


Scratch is great for education, it is a very basic, and very limited programming language, set up to help young children learn programming. AOZ is designed to help children and adults of all ages to learn programming, but it is also a very powerful, professional language, capable of creating commercial quality games and advanced programs. It makes programming easier for beginners and professionals alike!




Can I share or sell the programs I create with AOZ Studio?


YES! Once you've paid the license for AOZ Studio, you can create an unlimited number of applications with it. Those applications are license free, and will remain license-free. That means that you can share or sell your software without paying us any royalty.
For the license fees, please check the Download AOZ Studio web page.

Even if you discontinue a monthly license fee, you can still share or sell your programs, however, without the paid AOZ license, you will not be able to modify or update your programs if required.




Can I still sell my program if I stop paying the license of AOZ Studio?


Yes, however, you will not be able to modify your code. If you don't need to update or maintain your program, that is fine. See the previous FAQ for more information.




Do you have the list of the instructions of AOZ?


There is a work in progress (we keep adding ones) list on the Download AOZ TAB of this web site




Is the code of AOZ open source?


YES! It always will be. You can even use your own creativity to extend the language, etc.

The transpiler is proprietary to AOZ Studio and supplied under a non-exclusive license. (See the Download AOZ Web page for more information.) The license can be read and accepted by installing the product.




Is there a special version for Schools?


Is it the same version but we are not asking for a license fee if it is for under 16 yo “official” school teaching (not individuals or families). We want to allow the young kids to learn with a free product.




Can I participate in the development of AOZ Studio?


YES! You're welcome to contribute. Please contact us and describe your background, and how you would like to participate.




Can I share my code on GIT?


YES! As for how to, we will answer later when we have that well organized.




Care you going to make accessories to edit the sprites in the future?


YES! A sprite editor will be integrated with the IDE along with other tools such as a sound creator, 3D object editor, etc. Stay tuned as we develop these and more...




Can I make the pictures with Adobe® Photoshop®, and import them into my AOZ Studio application?


Adobe® Photoshop® is capable of exporting images in formats that are usable by AOZ Studio. Consult your AOZ user manual for more information on how to import graphics.




What tools do you recommend for drawing sprites until the accessories are made?


Piskel is an excellent sprite editor that you can use for free. These sprites can be exported in a form usable by AOZ.
NOTE: Piskel is NOT made by AOZ Studio, and we are not responsible for it's function or content.




AOZ Studio uses Atom editor.  Can I change to Visual Studio Code or Notepad++?


The current version of AOZ uses a highly customized version of the Atom editor (a great product!). The AOZ IDE is integrated into Atom. You can use any text editor you like to edit your code, however, at this time, as the transpileur can be called in a command line, but this is not working anymore on the latest version, this will be back (no date yet).




Is AOZ a good language for beginning programmers?


YES! That is what it was designed for. Due to the simple syntax, you can learn step by step, on your own. You can also learn by using the provided tutorials and example programs. As you progress you can even learn more advanced topics like object oriented programming or JavaScript, but you don't have to. Learn at your own pace. You'll be amazed at how fast you'll learn! We're surprised every day by what new users create, and how fast they create it!




How do I submit bug reports and suggestions for AOZ?


We welcome your input so we can improve AOZ for you! We prefer that you use AOZmine, since it is our official platform for bug reports and feature requests. If you like you can also send us suggestions and bug reports via Discord AOZ Studio server, the AOZ Facebook group, and our Youtube AOZ Studio channel. Check out our Contact Page for more information.




Can I make serious applications with AOZ?


Absolutely! In addition to great games, you can create databases, web applications, business programs... anything you want! If you like, you can use advanced features like, OOP, integrated JavaScript coding, DOM integration, etc.


NOTE: DOM is the Document Object Model used for HTML web pages and XML documents.
XML is the eXtensible Markup Language used for databases and other purposes.
OOP stands for Object-Oriented programming.




Can I work with my friends on the same game?


Currently, AOZ provides a way to send a complete AOZ program including your code and all supporting files (graphics, audio, etc.) in a single file archive, (.AOZip), so you can easily share it with your friends. Then can then import that file into AOZ. Stay tuned... We may have more interactive collaboration tools in the future.




I want to access my local PC drives.  How do I do this?


Yes! When your run your application in the AOZ-Viewer (by pressing F2 in the editor), your application has a complete and transparent access to the filesystem of your machine. It is also the case when you export your application as an executable… On the contrary, you will not have access to the local filesystem if your application is running in a browser.




Can I make a web site in AOZ?


YES! We've included DOM instructions in the language. Examples of website creation are included.

NOTE: By default, most AOZ applications will run on the web.




Can I make a server in AOZ?


Not yet, but this is a feature that will be available in a future version of AOZ Studio.




Can I access mySQL databases in AOZ?


We are working on an easy to use database extension. We will also have local storage features. This is planned for end of Q1 2021




How can I import an AMOS 1.3 or AMOS Professional program?


AOZ is not 100% AMOS-Amiga compatible, but quite close. Most of the code and banks will import automatically, when you load a .AMOS program.
We've also included with AOZ, an original Amiga Game: CyBall, which was imported into AOZ, as well as a tutorial on how this was done. Check on Youtube the video from Phil Bell on converting an AMOS to AOZ game: https://youtu.be/E0Rm4PNil9o




Will my Amiga AMOS or AMOS Pro game really work everywhere today?


Most of the AMOS code work, but some adjustments may need to be made. The current version of AOZ is very Amiga friendly, but not 100% compatible. Although in the future, there may be improvements to AMOS Professional compatibility, AOZ is not intended to be an Amiga/AMOS pure emulator.

Thanks for being patient, Amiga fans!




How much faster is AOZ compared to AMOS?


The quick answer is: It should be a LOT, LOT faster! :-) With that said, it's hard to give a specific answer regarding speed, since this depends on many factors. Just how much faster, depends on your operating system, the web browser you're using, how fast your computer hardware and memory is, etc.





How many sprites and bobs can I have now?


In AOZ, the number of sprites and bobs is virtually unlimited, and largely determined by the memory capacity of your computer and web browser.




Modern machines are in true colour.  I used a palette on the Amiga...


You can use both in AOZ! If you want to use a colour palette you can, but you can also set colours directly. It it's default mode, AOZ is fully capable of using true colour graphics as well as alpha/transparency/opacity. That's 24 bits of RGB colour, in addition to 8 bits for alpha (a total of 32-bits). The colour palette can store any combination of those colours.

If you want more compatibility with your Amiga programs, you can opt to run in Amiga mode, which will provide you with standard 12-bit colour, as well as half-bright, etc.

NOTE: The level of color support varies from command to command. All commands support 24 bit color, however, not all commands support alpha at this time.




Does it support Dual Playfield for parallax scrolling?


Yes! With AOZ, the number of levels of scrolling you can use are only limited by memory and hardware. In addition, when in AOZ mode, the number of colors used on each playfield / scrolling area is unlimited!




Can I use the Copper effects in AOZ, fade, rainbows and all this?


The rainbow and fade commands will be fully implemented in the final product. Additional copper support may be provided as well.




Is AMAL supported too?


Absolutely! AMAL will be fully supported in AOZ.

My game used a specific Amiga font. How can I use it now?

Several of the standard Amiga Fonts are included with AOZ. These include:
2001, arial, emerald, ruby, garnet, onyx, courier, helvetica, opal, times, ammolite, diamond, broadway, lines, mFast, News, peridot, Pica, sapphire, and topaz. Here are some notes on using these, and other Amiga fonts:


1. You can use Get Fonts just as you would on the Amiga to load your fonts.
2. To use an Amiga font, you can use the Set Font n command, just as you would in AMOS.
3. You can also use the Font$(n) array to dislay font information.

4. In addition to the old methods, you can also use the #amigaFont “fontname” tag to load an Amiga font.
Then you can use Set Font font$,size to select your font by name, and the size in pixels (height).
For example:

#amigaFont "sapphire"

Set Font "sapphire",24
Text x,y, "This is in 24 pixel high sapphire"

NOTE: In addition to Amiga fonts, you can now include Google Fonts as well!




I want to convert my game from the Amiga resolution to full HD.  How can I do this?


That depends on exactly what you want to do. If all you want to do is to scale it up, so your game will fit the full screen height, you don't have to do anything. By default, your game should scale to fit the larger display, but since the Amiga had a much smaller screen, and a different aspect ratio (proportion of width to height), there will be empty space to the left and right of the display. Also, the graphics will become "pixelized" (blocky).

If you want to fill the entire display, but you don't want to re-write your code, you can stretch the display in your program using Screen Scale x,y where x and y are the multipliers for the screen's width and height. The drawback is that this will distort (stretch) the display horizontally.

If you want to re-code your game so it actually utilizes the entire display, and does not stretch or squash the appearance of your graphics, this is where it can get complicated. There are many factors to consider.

1. If you use Amiga mode, this will limit your screen sizes to the Amiga resolutions, so if you want to support full high definition displays, you'll want to change to AOZ mode. You do this using the #manifest tag. Just put the following tag at the top of your code:

#manifest: "aoz"

If you'd rather deal with the limitations, and use Amiga mode, you'll need to use:

#manifest: "amiga"

2. By default, AOZ mode will use 1280 x 720 as the screen resolution. This will scale properly to fit a high definition display. It's the same aspect ratio: 1.78:1, (1280/720 or 1920/1080).

3. For full high definition, you'll want to use a screen size appropriate for your high definition display. For example: For a 1080p monitor, you'll want to use a screen size of 1920 x 1080 in order to get the best quality graphics. You can also use 4K or 8K resolutions.

For example:

Screen Open 0,1920,1080,32,Lowres ' 1080p monitor (2K)
Screen Open 1,3840,2160,32,Lowres ' 4K monitor
Screen Open 2,7680,4320,32,Lowres ' 8K monitor

Now, you'll just have to modify your code to properly fill the larger display area. It's up to you how to do it!.




My game loads files from the DF0: floppy on the Amiga.  Will it still work?


You can't connect a physical Amiga floppy disk drive to AOZ, however, if you transfer the files to your computer, you can create a DF0 folder in the AOZ filesystem folder so you can access your files using the DF0: drive name.




Are the keycodes of the Amiga or the PC?


That's a complex question, but in short: In Amiga mode, Amiga scan codes are supported. In AOZ/PC mode, the codes produced by the JavaScript Keyboard API are supported.

Similarities:
If you're talking about the printable characters, (alphabetic, numeric, special symbols, etc.), that would normally be returned by Inkey$, Input or Line Input, these will be the same on in both Amiga and AOZ mode. The arrow keys should return the same values on both Amiga and AOZ mode. Also, Keyname$ should be the same for both Amiga and AOZ modes.

Differences:
If you're talking about scan codes...

Amiga mode: If you use Amiga mode, most keys will translate directly to Amiga scan codes.

AOZ/PC mode: If you use AOZ/PC mode, the keycodes do not represent scan codes on a PC

keyboard. Instead, they return the codes provided by the JavaScript Keyboard

API through the KeyboardEvent.

Modifier keys: (shift, ctrl, alt, windows, cmd, etc.) These return bit flags, which can be used in

combination, and can be read at any time. They are also stored with each key

pressed. These are mostly the same in both Amiga and AOZ modes, but there

are some differences.

The Scan Code Tester program has been included with AOZ to help you sort out all the details and differences between keyboard handling on the Amiga and AOZ modes.




I would like to have the mouse pointer of the original AMOS back.  How can I do this?


Yes, you can do this within your AOZ programs. One way would be to hide the standard pointer, then create a sprite or bob with the image you want for the mouse pointer, and create code for it to follow the mouse.

Once it has been implemented, you can use the Change Mouse n command to switch between the standard pointer, crosshair, and busy pointer.

Within the IDE itself, this would be difficult to accomplish, although with some effort it might be possible.




Where is the source code of my software?


By default, your source code will be saved in the Documents/My AOZ Applications folder on your computer (under Windows). If you choose to save it elsewhere, that's up to you. Each application will have it's own sub-folder, which will contain the source code, and all supporting media and data files.




Where are the images, sprites, sounds?


By default, each application's folder will be stored in the “My AOZ Applications” sub-folder of the Documents folder on your computer. All of the associated graphics, audio, video, and data files will be stored in sub-folders of each application's folder. For example:

My Documents
My AOZ Applications
ReallyCooolProgram
html
resources
1.images
2.icons
3.musics
4.sounds

appicon
filesystem
main.aoz

Note: The numbered folders in the resource folder correspond to the banks that were used on the Amiga.





My game used an extension to play tracker music.  How can I play it now?


AOZ has a built-in extension capable of playing SoundTracker music files. The tracker engine used supports not only the Amiga sound tracker files, but newer formats supporting up to 32 channels, XM audio and more.




My game seems to crash the browser.  It becomes very slow...


This could be for many reasons. Here are some possible answers:

1. AOZ works with most modern web browers, but it's possible you may be using an incompatible web browser.

2. You my have have an error in your code that is causing the slow down. Try checking out your code with the debugger.
3. You may be trying to access a device that is not available or does not exist.
4. You may need to add the instruction: Wait Vbl inside very fast loops. Without Wait Vbl, AOZ may run too fast to complete all operations before the next loop starts. This can slow down your programs.




I don't want to see the orange / red screen any more when my game starts.           How can I remove it?


Here's the short answer: Add this in your program, just after the opening tags (if you have any):

Paper 0 : Cls

Here's the long answer: AOZ has an array of colours attached to each screen. This array is called the Palette. You can change the colours in the Palette if you like, but if you don't, and you're in Amiga mode, the first three colours (0, 1, and 2) are black, orange, and white.

There are also two instructions you can use to select the colours you use to print text on the screen. These are Pen pn and Paper pa, where pn is the index of the colour you want to use for the Pen (text), and pa is the index of the colour you want to use for the Paper (background). In Amiga mode, by default, the Paper colour is 1 (orange), and the Pen colour is 2 (white)

So, if you run an empty program in AOZ, you'll see the area of the screen in the Paper colour.

If you don't want the orange screen, the easiest way to change that is to select a different Paper colour, and then clear the screen.

Paper 0 : Cls

NOTE: If you don't want to change the Paper colour, alternatively, you could just use:

Cls 0

This would work, however, since the Paper colour wasn't changed, any text you print will still be printed on an orange background.





Can I use the joystick of my PC as I used the joystick of my Amiga?


Yes, you can! You can use USB joysticks / gamepads with the standard AMOS joystick instructions: jUp(n), jDown(n), jLeft(n), jRight(n), Fire(n), and Joy(n) (...where n is the number of the gamepad). There are also additional gamepad instructions provided in AOZ. Consult the documentation for more information.




When can I import my Atari STOS programs?


The initial release does not have a STOS mode (manifest) provided, however there are plans for this capability at a later date.




I like line numbers.  Can I keep them?


Yes you can! AOZ supports line numbers as well as alphanumeric labels, just as provided in AMOS and other versions of BASIC.




I hate line numbers.  Can I remove them?


Yes you can! Although line numbers are available for use, they are not required. You can use alphanumeric labels if you prefer.




What is a manifest?


A “manifest” is a file containing “metadata” (data that describes other data). This metadata describes and/or configures a group of accompanying files that compose an entire project. For example, typical information that may appear in a manifest would be the program name, version number, license information, and a list of the files that are a part of the entire program package. Configuration settings may also be included. For example: An AOZ application's manifest has information about the platform (AOZ or Amiga), the emulated display size, default colour palette, and fonts used. The manifest can be stored in the folder with the .aoz file or in its resource folder.




I do not understand the manifest.  Do I have to use it?


You don't have to know anything about the manifest. It is only needed if you want to customize some of the settings used in the default manifest. You don't have to create a custom manifest for your programs at all though. The most important settings can be configured using tags in your AOZ code.




What is the .hjson format used by some files in AOZ?


You don't need to understand these unless you want to. They're used internally by AOZ for storing and transferring data between AOZ components and the user. With that said, JSON is JavaScript Object Notation. HJSON is a simplified extension of JSON intended to make it easier for Humans to read and edit data before passing it to the computer.




How can I debug my applications?


This is a big topic! There are many ways to debug applications beyond the scope of a simple FAQ, but let's go through a few of them:

1. Character case. Remember that variable names in AOZ are case sensitive. (Instructions are NOT case sensitive.) For example, all of the following represent DIFFERENT variables in AOZ:

Stuff$="stuff"
stuff$="different stuff"
STUFF$="still different stuff"
sTuFf$="yet more different stuff"

If you have the wrong case on your variable names you'll be referencing different variables.

2. Syntax highlighting. AOZ's editor provides for syntax highlighting where keywords, constants, variables, comments, etc. all appear in their distinct colours. If the colour isn't right, you may have a typo in your code.

3. Context-based pop-up help. As you type the first few characters of a command, you'll see a drop-down list with commands and keywords in it. Use the up and down arrow keys to highlight the command you're concerned with. You'll see a brief description of the command and its parameters to make sure you have them in the right order and format.

4. The Print statement! This is one of your most powerful – and easy to use debugging tools! If you want to know the value of a variable at a particular point in the code, just insert a print statement at that point in the code. If you want to stop at that point so you can make sure what you print isn't erased by another command, you can insert a Wait Key statement immediately after your print. That way, you can see the value you wanted, and the program will wait until you press a key before continuing.

5. Comments! You might not think comments would be useful, but when you're getting an error, and you're not sure where to look, you can just comment the entire block of code where you think it might be happening. When using this method, it's best to make sure your normal comments in your code use one of the other two methods. The double-slash // or the single quote. ' That way, you can use the block comment indicators /* */ to comment large blocks of code without problems.

For example, if your program starts, and then the screen goes black with no error message displayed, you could use this method progressively to discover what portion of the code contains the problem. Start just after the first few executable statements, and use a block comment to disable the rest of the program. You can use this in combination with the Print statement to make sure the code is functioning up to the opening comment mark: /*. If the program is working up to that point, then move that opening comment mark further down in the code until you narrow it down to the failing code.

6. Transpiler Window: If there is an error that prevents the program from transpiling properly, you'll see a list of errors in the transpiler window. When a program fails this way, the editor window should already be open and pointing to the error in the source code. If not, look in the transpiler window for the line number and character where the error is in your application (usually main.aoz). Look for that line number in the editor, and the specific character.

7. AOZ Viewer: When compiling in the AOZ viewer you'll have additional debugging options, like the Inspector, and Direct Mode. (Consult the AOZ documentation for more information about these features.)

8. JavaScript Debugger: For more advanced debugging, you can use your web browser's JavaScript debugger. (Consult the AOZ documentation and your web browser's documentation for more information about using a JavaScript debugger.)

9. The Direct Mode: if you press CONTROL-C to Stop your program running -in the AOZ-Viewer window-, you can enter the direct mode by pressing ESCAPE. Direct mode allows you to type any command, the command being executed immediately when you press ENTER. The database of the previously running application in not erased, allowing you to print out variables, arrays, or any information currently contained in your application. The output of the Print command is redirected to the direct mode console, allowing you to see the data even if your game owns the display. Bob, Sprite and all normal command can work.
All the timer-based automatic animations and movements will continue to run.

Example (press SHIFT-ENTER to type multiple lines statements):
> For A = 1 To 5
Print POSITION( A )
Next
5
10
600
20
2




How can I export my software?


If you want to share your program with others, you can:

-export it in a way to share with other AOZ Studio users.

-use the Publish option to put your program ready on the internet for anyone to use.


How to:
If you want to share your program with others, AOZ Studio helps you export your entire folder for your application just by clicking on the Save As icon on the toolbar at the top of the screen. There you can select many ways you can Export/Save your program. These options currently include:

* AOZ A standard AOZ application folder: Mainly to save on your computer. Note there is an autosave by default, you can notice a small round on the source code Tab (near the name) that shows IT.
* AOZIP An archived AOZ application folder (package): Mainly to share with others.

* HTML5 An executable HTML5 application.

In the future, we will also offer:

* EXE A real executable application
* APK An Android Package

Whatever your choice is, you'll be given the option to select the destination drive and folder for your application, as well as a new name if you prefer.

In addition to Save As, you can also click on the Publish icon to put your program out there for anyone to use. You'll be provided a link to your program that you can then share with friends and family to show them your creation!




What is a global variable?


Normally, variables created inside the main .AOZ code are only accessible in the main program. In other words, normally, Procedures, Functions, and Instructions would not see these variables unless they were passed as parameters. If you want a variable defined in the main program (usually main.aoz) to be accessible in any Procedure, Function, or Instruction, you need to use the Global statement. For example:

Global X ' makes X accessible anywhere in your program.




What is a local variable?


A local variable is only accessible inside it's own “container”. In plain English, that means that if you create a variable inside a Procedure, Function, or Instruction, that variable is only usable inside that “container”. The main program would not be able to see or alter these variables unless given permission to do so by the use of a Global or Shared instruction.




What are the rules for local and global variables in AOZ?


1. Variables defined inside a container are local to that container unless otherwise specified. In plain English, that means that if you define a variable inside a Procedure, Function, or Instruction, (the containers) that variable is, by definition local to its container, and only accessible inside that container. (See example below.) For the following text I'm using a “Procedure” as the example container.

2. You can duplicate variable names inside different Procedures, since they are only accessible inside their own container. For example:

X=1 : Y=100

Procedure FirstProc
X=10 : Y= 5
SecondProc
Print X,Y
End Proc

Procedure SecondProc
X=3 : Y = 2
Print X,Y
End Proc

FirstProc
Print X,Y

You can see by the results (below) that the values for X and Y are independent for each procedure and the main program.
3 2
10 5
1 100




What is a Shared variable?  How are they used?


Shared is similar to the Global instruction, except that it works in the opposite direction. When you are inside a Procedure, Instruction, or Function, Shared allows a variable defined inside a container to be visible to the parent container. The parent is usually the main program. For example:

Procedure DoStuff
Shared X
X=10
End Proc

DoStuff
Print X

The result would be the number 10. Without the Shared statement inside DoStuff, the result would be 0, since X was not defined in the main program, and X would be local to DoStuff.




How do I share global variables across modules?


You cannot. Modules and extensions are independent pieces of code and all their variables are private to the module or extension. The only possible way to do it would be by using pure Javascript code and writing the content of the variable in the “aoz” object).




Why do I get a type mismatch error?


First, let's understand variable types. AOZ uses several types of variables:

Integer: An integer is a whole number with no fractional / decimal portions.
It is named using normal alphanumeric characters. For example:


MYINT = 10

Number: Another type of number is a floating point or real number. These have a # symbol at the

end of the variable's name. These are numbers that may include a fractional portion of the

number. For example:

MYFLOAT# = 10.75

String: A string variable is a series (string) of alphanumeric charaters. Each character (byte) in

a string contains a single ASCII character. Strings use a $ at the end of the variable's

name. Double-quotation marks surround string constants. For example:

MYSTRING$ = "My String 3.53 ___ <<"

With that said, a type mismatch occurs when you try to set a variable to the wrong type of data. For example:

MYFLOAT# = "17.5"
MYINT = "Fred Flintstone"

Keep in mind that Procedures' and Functions' parameters and return values also have specified types. Passing the wrong type in a parameter, or treating the return value as the wrong type will also result in a Type Mismatch error.






How can I enter a colour in my palette?


Use the command: Colour number,c

number is the index of the colour in the palette
c is the new colour ' (an integer)

When indicated by a single number, colours in AOZ are usually entered as hexidecimal numbers where the first 2 digits are red, the next two are green, and the last 2 are blue. For example to set colour 0 to bright green, we might use:

Colour 0,$00FF00

NOTE: The $ preceding the colour indicates that the number is in hexidecimal.


If you don't understand hexidecimal, that's OK, AOZ provides a function to make this easier:

Colour 0,RGB(r,g,b) ' where r = the amount of red, g = the amount of green, and b = the amount of blue. Each of the r, g, b values corresponds to a single byte, so the range is 0 to 255. Using the same example of bright green from above:

Colour 0,RGB(0,255,0) ' with decimal parameters
...or...
Colour 0,RGB($0,$FF,$0) ' using hex parameters




How do I specify hexadecimal and binary numbers?


Hexadecimal numbers have a $ preceding the number.
Binary numbers have a % preceding the number.

For example, all of the following set X to 250:

X = 250
X = $FA
X = %11111010




How do I convert a string to a number?


N = Val(X$) ' This converts X$ to an integer (N).




How do I convert a string to a number?


X$ = Str$(N) ' This converts N to an String (X$).




How can I have quotes in the strings in my source code?


The double-quotation mark “ has the ASCII value of 34, so you can insert a quotation mark in a string using the function: Chr$(34):

X$="This string has "+Chr$(34)+" qoutes"+Chr$(34)+" in it."




How to I put remarks / comments in my code?


There are several ways. You can use the old style remarks as in earlier versions of BASIC:

You can use the old style REM instruction:

REM this is a remark

NOTE: As an instruction, this remark has to be at the beginning of a statement. For example:

qty=12 : REM set the quantity to 12

Above, the statement separator (:) is required when using this type of remark.

You can also use the BASIC style single-quote remark (as AMOS Pro allowed). Anything following the single-quote is considered a remark. Example:

qty=12 ' set the quantity to 12

You can use the JavaScript style single line remark. It works similarly to the single-quote. Anything following the double-slash is considered to be a remark. Example:

qty=12 // set the quantity to 12

Finally, you can now use a multi-line comment in AOZ. These work the same as they do in JavaScript, C, and other modern languages. Since they comment whole blocks of code, there is a start comment and end comment code:

Start comment: /*
End comment: */

Anything between the start comment and end comment marks will be considered to be a remark. For example:

/*
All of the text here is considered to be a comment,
no matter how many lines are between the start and

end indicators.

When the /* is detected, everything following is

considered to be a comment (even another start
indicator) until the end indicator is detected:

*/

NOTE: Multi-line comments are very useful for debugging code!




Should I use GOTO?


This has been a matter of debate among programmers for years. Goto has gotten a bad name since historically, careless programmers have abused this statement, and created “spaghetti” code that is very difficult to follow and debug. With the advent of other alternatives in modern languages, some purists say that the Goto instruction is never needed. Others believe that it is still appropriate in certain cases. The Goto instruction is provided to let the programmer decide which instruction is appropriate.

With that said, AOZ provides you with a wide variety of control structures and instructions you can use as alternatives to the Goto statement if you prefer. These include Proc, Gosub, Gosub n, Gosub l$, Gosub/Return, While/Wend, Repeat/Until, On/Proc, On/Gosub, Every/Gosub, Every/Proc, Exit, Exit n, Exit If, Pop, Pop Proc, etc.




How do you achieve GOTO in a browser?  I thought this was impossible.


It's not impossible. AOZ keeps track of every line number and label, and utilizes the power of JavaScript, HTML5, CSS3, and other modern web technologies to do its magic!




Why is my application a little slower when I use GOTO or ON ERROR GOTO?


When using Goto, it is necessary to create a separate code block for each line of code to keep track of every line number and label, and the error positions if they occur. This requires a lot of overhead!




What is the browser doing when I use Wait or Wait Key?  Does it eat processor time?


The main code of your program will stop when the Wait n# or Wait Key instructions are encountered, however any background operations already in process will continue while AOZ is waiting for the time to elapse, or the key to be pressed. These background events could include AMAL animations, Tracker music and more.




My program is too slow.  How can I speed it up?


A book could be written on this topic! There are numerous methods to speed up your code.
Here are a few ways:

1. Make your graphics smaller.
2. Use less colors when you don't need them.
3. Make your music files smaller.

4. Make your video files smaller.
5. Avoid “hard” waits. For example:
Wait Key is a “hard” wait. It will stop processing your code until a key is pressed.
Key State or Inkey$, on the other hand, will allow processing to continue while waiting for the keypress.

6. Reduce “hard” waits. For example, if you're using the AOZ manifest:
Wait 1 ' is a hard wait. This will wait for 1 full second.

Wait 0.5 ' would be better. This waits ½ second.
Wait Vbl ' is usually best. This is dependent on the refresh rate of your monitor.

NOTE: In Amiga mode, the wait amount is in 1/50th second intervals vs. seconds.

NOTE: If you're doing a LOT of processing in your code, you may choose to remove the Wait
altogether, but be careful! If your program runs too fast, it could be counter-productive, and

actually slow it down or lock the program if there is not enough time to perform all of the
operations required.

7. The Timer function can be used to test how fast a block of code is. You can use this to compare
different versions of your code to see which one is faster. For example:

T#=Timer : Done=0
Repeat
...your code here...
Until Done
HowLong#=Timer-T#
Print “It took “;HowLong#;” ms.”




My program is too fast.  How can I slow it down?


The usual method is to use the Wait Vbl command just before the end of the loop you'd like to slow down. Wait Vbl will wait 1/50th of a second in the Amiga manifest, and will wait for a time dependent on your monitor's refresh rate when you're in the AOZ manifest.

You can also wait a specific amount of time by using Wait n#. In AOZ mode, n# is in seconds, and may use increments as small as milliseconds (ms). In Amiga mode, n# is treated as an integer, where 1 indicates 1/50th of a second, so Wait 3 would wait 3/50th of a second.




What is the most efficient way to concatenate many strings together?


If the strings are different, the simplest way is to use the + sign.

X$=Y$+"two"+C$

If you want to create a string that is a repeated pattern, you can use Repeat$ For example:

r$=Repeat$("<=>",10)
Print r$

result:

<=><=><=><=><=><=><=><=><=><=>




Can I subtract strings in AOZ?


Yes you can! String subtraction is a unique feature of AOZ. It removes all occurrences of a string in another string. For example:

X$="ABC123DEF123GHI"
Print X$-”123”

result:

ABCDEFGHI




What is an Array? How do I create and use them?



In AOZ, an array is a series of integer numbers, floating point numbers or strings. They are referenced by indexes which are numbers representing each item's position in the array. These number of indexes is referred to as the dimension of the array. An array with a single dimension is similar to a single column in a spreadsheet. An array is initially created with the Dimension statement. For example:


Dim X$(100) ' An array of 101 string variables.

Dim X#(100) ' An array of 101 floating point numbers.

Dim X(100) ' An array of 101 integer (whole) numbers

To refer to a specific item in an array, you use the array name followed by an index in parentheses.
For example:


X(5) = 20

Print X(5)

result:
20




How do you make an array in AOZ?


Use the Dim instruction. For example:

Dim X(10) ' array of 11 integers with indexes from 0 to 10.
Dim X$(5) ' array of 6 strings with indexes from 0 to 5
Dim X#(20)' array of 21 floating point numbers (indexes 0 to 20)

NOTE: If the 0th element of the array bothers you just don't use it, but it will be there if you need it.




How do you make a multidimensional arry in AOZ?


AOZ supports multi-dimensional arrays with any number of dimensions. All you have to do is separate each dimension by a comma when you define the array: For example:

Dim GRID(8,8) ' 8 x 8 array of integers (indexes from 0 to 9)

NOTE: If the 0th elements bother you just don't use them, but they're available if you need them.




How do I store data in my AOZ program?


We have local storage, soon database for very large data, but for very few data an easy method is to store data in your programs using variables. If you have a large amount of data to store, you also can use the Data instruction in conjunction with the Read and Restore instructions. Read is used to read input data into variables from the Data instructions in your program. For example, the following code reads 10 numbers from the data on line 10 into the X$() array:

Dim X$(20)
For i=1 To 10
Read X$(i)
Next i
10 Data "abc","def","ghi","jkl","mno","pqr","stu","vwx","yz","---"
20 Data 11,6,42,55,44,22,21,17,1,2,3
theDat: Data 9,8,7,6,5,4,3,2,1,0

Each time the Read statement is executed, the next piece of data is read from the Data statements in the program. For example, if one more Read statement is executed on the above code, the first number on line 20 will be read (11). The Restore statement is used to reset the pointer for the read statement to point to the first piece of data on the specified line number or label. For example:

Restore ' will point the next Read to the first piece of data
Restore n ' will point the next Read to the first data on line # n
Restore L$ ' will point the next Read to the first data on at label L$

For example: If in the code above, L$ contains “theDat”, this will point the next Read to the first piece of data on the line following that label (9). For example:

Restore L$ ' point at the data after the L$ label
Read X : Print X

result:

9




What is a Procedure and how do I use it?


A procedure is a self-contained block of code (a code container) that has a series of AOZ statements inside it. It can have it's own (local) variables. It can also have parameters passed to it. Here's how a basic Procedure is defined:

Procedure MYPROC[param1,param2$]
X=5
Shared Y
Y=12
Print X,param1,param2$
End Procedure

NOTE: End Procedure may be abbreviated as End Proc.

The above procedure is called MYPROC. It has two parameters: param1 and param2$. It also has one local variable X, and one Shared variable Y. A procedure is called just using it's name along with any required parameters between square brackets, and separated by commas. To all the procedure above, you would add a line like this to your code:

MYPROC[123,”abc”]

The resulting output would be:

5 123 abc




How do I create my own instructions?


Part of the beauty of AOZ is that you can create your own customized instructions. It's a bit involved for just an FAQ, but we'll give you a start here. An Instruction is defined similarly to a Procedure. Here's how they're different:

When called, an Instruction's parameters are contained withing square brackets vs. parentheses.
An Instruction can't have a return value. A procedure has an optional return value.
An Instruction becomes a part of the language for the program it's in, and can potentially become a part of the language for ALL the AOZ programs you write. A procedure doesn't work that way.
When defined, the Instruction's parameters name may be in double-quotation marks to allow for multi-word instruction names, and the parameters are just separated by commas with no brackets or braces around them.

Here's an example of an Instruction to draw a right triangle, where _x and _y are the corner with the right angle, and _Len is the length of the sides adjacent to the right angle.

Instruction "RightTriangle",_x,_y,_Len
Draw _x,_y To _x+_Len-1,_y
Draw _x,_y To _x,_y-_Len+1
Draw _x+_Len-1,_y To _y-_Len+1
End Instruction

You can call your new instruction like so:

RightTriangle 100,100,50




How do I create my own functions?


Part of the beauty of AOZ is that you can create your own customized functions that can become a part of the language! It's a bit involved for just an FAQ, but we'll give you a start here. An Function is defined similarly to a Procedure. Here's how they're different:

1. A Function becomes a part of the language for the program it's in, and can potentially become a part of the language for ALL the AOZ programs you write. A procedure doesn't work that way.

2. When defined, a Function's parameters name may be in double-quotation marks to allow for multi-word function names

3. When defined, the Function's parameters are just separated by commas with no parentheses or brackets around them. Here's an example of a simple function in AOZ:

Function "Area Rect", _x, _y
area = _x * _y
End Function (area)

You can then use our new function like any other function in AOZ, putting the parameters in parentheses:

Print Area Rect(3,4)

result:

12




What is an extension?


Just as in AMOS Pro, AOZ gives you the ability to create your own extensions. In AOZ, however, it is much easier, since you can code them in AOZ (and optionally in JavaScript) instead of using assembly language. Consult your AOZ user manual for more information on creating extensions.




How do I create an extension?


This is a rather complex topic for just an FAQ. Let's just say that it's easier than creating an extension in AMOS Pro. No assembly language programming is required. JavaScript coding is useful, but optional. You can create a working extension with *only* AOZ code! (Consult your AOZ user manual for details on creating your own extension.)





I need to use Javascript to do a specific task. How do I do this?


You can easily integrate JavaScript code into your program using the curly braces. { } Any code inside the curly braces is treated as JavaScript. For example:

{ alert('I am running JavaScript inside of AOZ!'); }

You can also return values from JavaScript:

Print { document.location }




How do you make a multidimensional array in AOZ?


AOZ supports multi-dimensional arrays with any number of dimensions using the Dim instruction.
For example:

Dim X(10,20,5)

...creates a 3-dimensional 10 x 20 x 5 array called X.




Is it necessary to use Javascript?


It is not necessary to understand or code in JavaScript to create and run AOZ programs, however, the code generated by the transpiler, requires JavaScript to run.




What is a transpiler, and how does it compare to a compiler.


A compiler takes the language source code, and converts it to native machine code for a specified platform or platforms. A transpiler, converts the source code from one computer language to another. In the case of AOZ, the AOZ source code is converted into equivalent HTML5, CSS3, and JavaScript source code, and adding all required supporting libraries to make a complete application.




Will the AOZ Transpiler export to other languages than JavaScript?


At this time HTML5/JavaScript and HTMLDEMO (for Facebook) are the only target languages, however, many new export capabilities are planned in the future (such as c++, c#, swift, java, python).




Why did you choose to make a transpiler instead of a compiler?


Compiling to machine code is unique for each platform, and complex custom coding is required for each unique platform. The transpiler gives us the advantage of being able to transpile into a platform independent language, such as JavaScript, allowing us to use the identical code for each platform. We can also leverage the numerous JavaScript libraries.

The great advantage of a transpiler compared to a compiler, is that a transpiler outputs an already high-level (but fast) language. As JavaScript runs on almost every existing computer platform available today, it was the obvious choice. If we had chosen the path of making a compiler, we would have had to produce not one, but three different sets of source-code, one for every Operating System, Windows, macOS and Linux.

Please note that the transpiler is aimed to be expanded, multi-language export will be added. This means that in a certain future, you will be able to export your application in C# or Swift. C# application will be able for example, to use Unity as a renderer, thus opening the gate to real consoles for AOZ Applications.




Can the AOZ Transpiler export node.js applications?


Not at this time, however many new export capabilities are planned in the future.




Can you integrate the AOZ transpiler in a compilation chain with MAKE?


Not at this time.




Does the AOZ Transpiler generate a log?


Not by default. You can, however, turn on logging using the tag:

#log: true

The #logto: tag can change where the log is stored. Consult the AOZ documentation for more detail.




How can I disable the “variable not defined” warnings?


Use the #nowarning: tag at the top of your code. Consult the AOZ documentation for more details.
This method will disable warnings for a specific application. To ignore these warnings in ALL applications, you'll need to edit the transpilermanifest.json file inside the aoz folder. There is a sections called “warnings:”. Insert any error messages you do not want to see there. For example:

warnings:

{

'variable_not_declared': true,

'instruction_not_implemented': true,

}




Are there pre-processor commands in the AOZ transpiler?


AOZ includes a number of tags that may be placed inside an AOZ program that can configure various settings that will be used when transpiling code. There are dozens of tags with a wide variety of functions. See TAGS in this forum.
For example: The most commonly used tag, that we set by default in the manifest so you do not have to take care of it, is:

#manifest: "aoz"

This configures AOZ in it's standard platform configuration used for Windows PCs.




TAGS pre-processor commands


AOZ includes a number of tags that may be placed inside an AOZ program that can configure various settings that will be used when transpiling code.


Below, tf indicates a true or false option.

#manifest: “p” Configures AOZ for a specific target platform (p). Ex: #manifest:"aoz"
Possible values for “p” at this time include:

“aoz” This is the default mode. It configures AOZ for modern computers supporting

web browsers with HTML5, CSS3, and modern JavaScript APIs, such as such as

Windows-based platforms.

“pc” (deprecated) This is synonomous with “aoz” mode, but has been included for

compatibility with code that was created in the pre-beta versions of AOZ.

“amiga” Amiga friendly mode. It makes the transpiled program function more like it

would in AMOS Professional on the Commodore Amiga computer. Although

NOT completely compatible, it provides an “Amiga friendly” environment for

importing legacy AMOS and AMOS Professional code to AOZ.

NOTE: This is intended for importing AMOS code. It would be of limited use

for targeting an actual Amiga computer or emulator. At this time, AOZ is not

suitable for generating native Amiga code.

Additional platforms that may be targeted in the future may include Linux and Atari (STOS).

#speed: “s” The speed (s) is a “governor” for the speed of the transpiled code. Options

include: “fast”, “safe”, and “graphics”.


“fast” Allows the transpiled code to run at maximum speed. In this mode, you'll have

to be careful to ensure that background operations can process. This is usually

done by including a Wait Vbl at the end of large loops.

“safe” This will slow down the code for safe operation if you're not using Wait Vbl.

“graphics” For graphic-heavy, fast, simple loops. (slower to allow time to update)
'doctag_speed: Multitask prehemption indicator -work in progress-.

Use "fast" if you are sure to have a Wait Vbl at the end of each large loop, "safe" if not

(example, Amiga games, slower), "graphics" for graphic-heavy fast simple loops (slower).',


#tvstandard: “s” CRT monitor emulation. Options are “pal” and “ntsc”.


“pal” Emulates the PAL (Phase Alternate Line) video standard. The official standard

provides for 625 interlaced lines displayed at 25 frames per second.

In AOZ, PAL mode provides 512 line (height) screens.

“ntsc” Emulates the NTSC (National Television System Committee) videos standard.

The official standard provides for 525 lines at 29.97 frames per second.

In AOZ, NTSC mode provides 476 line (height) screens.


#displayWidth: “w” Sets the width (w) of the canvas on the display in non full-screen modes. The

default is 1280 in aoz mode and 440 in amiga mode.'

#displayHeight: “h” Sets the height (h) of the canvas on the display in non full-screen modes. The

default is 1280 in aoz mode and 512 (PAL) / 476 (NTSC) in amiga mode.',

#fullscreen: tf If true, allows switching the application to full-screen mode. The application is

initially displayed in the whole surface of the browser with a clickable full-screen

icon pasted on the top of it.

#fullpage: tf If true, displays the application using the whole surface of the browser.

#keepProportions: tf If true, in full-page or full-screen modes, the dimension ratio of the application will be preserved, and empty space (appearing as bars) will be added

on the left & right or the top & bottom of the application as necessary. If false,

the application will be resized to the entire browser area and graphics may be

distorted.

#fps: tf If true, displays a fps indicator on the top of the applications's display.',

#basicRemarks: tf Default is false. If false, single-quotes ' will be used to indicate remarks. If set

to true they will be treated similarly to double-quotes. WHY NOT BOTH – AS

IN AMOS Pro?!


#tabWidth: n n indicates the number of spaces used for the TAB character in the code

produced. (The default is 4.)

#cleanExtensions: tf If true, the transpiler deletes the object folder of all extensions before transpiling

the application, forcing a complete re-transpilation of those extensions.

#cleanModules: tf If true, deletes the object folder of all languages modules before transpiling the

application, forcing a complete re-transpilation of those modules.

#clean: tf If true, deletes the HTML folder of the application before transpiling it, forcing a

complete re-transpilation of all files.

#sendcrashreport: tf If true, automatically sends a report after a crash of the application or the

transpiler to AOZ Studio, with information about the crash.

#export: “lang” Where “lang” indicates the output language of transpilation. The default is

“html”. You may also use "htmldemo" (for Facebook). Future languages may

include: "c++", "c#", "swift", "java", "python", etc.'.

#saveto: “folder” Path to a folder where the transpiled application is saved.

#logto: “folder” Path to a folder where the logs of the transpiler are saved. Default is aoz/logs.


#log: tf If true, saves the transpilation log. Default is false.

#googleFont: “name” Name of a Google Font to include in the application. (case insensitive)

#amigaFont: “name” Name of an Amiga Font to include in the application. (case insensitive)

#splashscreen: tf tf may be true or false. If true, inserts a splash screen at the start of the

application. This tag might not have any effect after initial test period and before

purchase of the product.

#splashwaitsounds: tf If true, adds 'Click to continue' to the splash screen, if the application

uses sounds, to bypass the browser protection and allow sounds when the

application runs. Does nothing if the application does not use sounds.',


#rainbowmode: “m” (Experimental) “m” may be "fast" or "slow" mode. If fast, rainbows are

displayed on a screen in the background containing the rainbow. If slow, a

full hardware simulation of rainbows is displayed (slower, but more precise).


#needserver: tf If true, indicates that the application can only run from a server, and forces the

automatic launch of a local web-server the first time it is run. Use this tag if you

use Javascript libraries that have not been completely adapted to AOZ.

#usesounds: tf If true, forces the "sound" indicator and makes the splash-screen "Click to

continue" upon start.

#nowarning: tf If true, prevents the transpiler from displaying certain warnings. (TBD)


#insertintohead: “t” Inserts specified text (t) into the HEAD section of the index.html file generated

by the transpiler.

#checkfornextloops: tf If true, enforces a check at runtime of the parameters of For loops, and

generates errors if the loops cannot exit before eventually crashing the browser.

Will reduce the speed of For loops.

#preprocvariables: Defines pre-processor variables to be used during transpilation. This variable is

initialized with a value of zero. Use #ifdef or #ifndef in your code to detect the

definition of this varaible.

#displayEndAlert: Display an alert dialog in the browser at the end of the application.

#displayErrorAlert: Display an alert dialog in the browser when an error occurs. Use with care, since

the program will become un-responsive.

#excludefrombuild: Exclude the extension or module from the general build (use it for development).


#forcetranspile: Force the transpilation of specified module or extension.

#developermode: tf If true, turns on detections of changes in extension and modules for automatic

re-transpilation. Will slow down transpilation.

#includesource: tf If true, copies the source code of the application as remarks in the transpiled

code. (True by default when in Developer mode.)





© Copyright AOZ Studio 2019-2020.  Made with love from AtoZ.

  • Facebook
  • YouTube

Follow us: