TUTORIAL

This page shows how to use of glUAE by means of practical examples. The amount of information might make it seems that glUAE is complicated, but it is just that there are lots of options (and lots of power) that can be exploited through few basic-user operations.

1. QUICKSTART
2. FLOPPY-BASED APPLICATIONS
3. HARDFILE-BASED APPLICATIONS
4. WHDLOAD-READY APPLICATIONS
5. AmigaDOS-BASED APPLICATIONS
6. AmigaDOS-BASED APPLICATIONS WITH THE CENTRALIZED SYSTEM
7. CLASSIC AmigaOS
8. SINGLE-FILE APPLICATIONS
9. SPLASH SCREENS

1. QUICKSTART

Probably the idea that firstly and mostly strikes the imagination of users is launching games residing in floppy images by just double-clicking on them.

The quickest solution is to define a project DefIcon for each image type desired (e.g. .adf), with the settings shown in this picture:

This way, each time an .adf image is opened from Workbench (even indirectly, e.g. through WBRun), UAE is started with the image mounted to DF0: and the next 1, 2 or 3 images in the same directory mounted to DF1:-DF3: in alphabetical order.

However, this only barely scratches the surface (and, emulation-wise, might give unsatisfying results in some cases, as .uaerc could be unsuitable): glUAE offers much more power and control.

2. FLOPPY-BASED APPLICATIONS

This section demonstrates how to launch an application coming on a floppy image using the oldschool demo Groovy by Lemon (its image Groovy.dms is available on Aminet).

The demo will be ready to run in a Workbench window after:

1. creating a directory where to put all the files;
2. storing the image;
3. adding a UAE configuration^example that contains the settings for best compatibility/performance;
4. adding a properly configured project icon.

A complete installation would look like this:

Launching the demo is simply a matter of double-clicking the icon. Of course, anything that is equivalent to a double-click has the same effect - e.g. these shell commands:

• WBRun .rc
• .rc
• RAM:Groovy/.rc

When there is no icon, it is possible to launch the demo by invoking directly the script glUAE_LA, whose argument can be any file belonging to the directory or even just the directory itself. Here are a few equivalent examples:

• glUAE_LA .rc
• glUAE_LA Groovy.dms
• glUAE_LA ""
• glUAE_LA RAM:Groovy/.rc
• glUAE_LA RAM:Groovy/Groovy.dms
• glUAE_LA RAM:Groovy

There are also many other possibilities: the Workbench menu, AmiDock, keyboard shortcuts, user scripts, etc. can all be used to launch the demo. Basically, anything that allows the execution of scripts is suitable.

3. HARDFILE-BASED APPLICATIONS

The case of applications residing in hardfiles is similar to that of floppy-based applications, except that:

• .hdf files take the place of floppy images;
• glUAE starts the emulation mounting 1 hardfile.

The hardfile mounted is the specific hardfile passed as input or, if none is specified:

• if there are multiple hardfiles, the one chosen by the user via a selector that is presented on the fly;
• the only hardfile available.

4. WHDLOAD-READY APPLICATIONS

No special operation is required to launch an application that is WHDLoad-ready: when glUAE detects the presence of a slave, it automatically starts the emulation ensuring that the application is run through WHDLoad.
E.g. after adding the icon and the .rc file^example, an installation of the game Lotus Turbo Challenge 2 would look like this:

In general, the slave fed to WHDLoad is the specific slave passed as input or, if none is specified:

• if there are multiple slaves, the one chosen by the user via a selector that is presented on the fly;
• the only slave available.

5. AmigaDOS-BASED APPLICATIONS

With the help of a hard disk-installed copy of AMOS Professional, this section explains how to prepare an application residing in ordinary AmigaDOS files.

Assuming that the development suite resides in a directory called AMOS_Professional (containing the directories Accessories, APSystem, etc. and the executable files), the steps required to get AMOS Professional ready to run are:

1. adding a UAE configuration that contains the settings for best compatibility/performance;
2. storing the minimal set of system files/directories (C, Libs, etc.)^example required to run the interpreter;
3. adding a minimal S/startup-sequence file^example that, at the end, launches the interpreter;
4. adding a dummy file called .no_centralized_system, which excludes the centralized system when not needed/desired (details about the centralized system are given in the next section);
5. addign a properly configured project icon.

More often than for games and demos, the usage requirements of applications may vary from time to time. Taking care of this is as easy as creating multiple UAE configurations for all the needs. At launch, a requester will ask which to use, as shown in the following picture:

To have the possibility of choosing whether to run AMOS Professional in a window or in a screen (optionally with sound), it has been enough to add the UAE configurations window.rc, fullscreen.rc and fullscreen+sound.rc.

6. AmigaDOS-BASED APPLICATIONS WITH THE CENTRALIZED SYSTEM

The previous section illustrated that applications (partially) relying on AmigaOS require some system components to be in their own directory. That, unfortunately:

• turns out to be very boring for the user, who has to find out all the needed components;
• is resources-consuming for the system, as more disk space is used and increases the overhead for single-file applications;
• causes all the disadvantages typical of duplication.

The obvious and ideal solution would be having a single, centralized operating system somewhere and getting all the applications to refer to it (which is exactly what operating systems are for). glUAE makes it possible.

On the system side, the user has to:

• put in any directory all the components needed by all the applications (of course, the best solution is a fully installed classic AmigaOS);
• inform glUAE about that directory during the installation.

• must make sure that the file .no_centralized_system is not present;
• must include the S/startup-sequence file that starts the application, if the S/startup-sequence file is present also in the centralized system;
• should include only the specific system files required by the application.

By exploiting this feature, the AMOS Professional installation considered in the previous section reduces to this:

(i.e. only the S directory remains).

7. CLASSIC AmigaOS

From glUAE's point of view, AmigaOS is nothing but an AmigaDOS-based application, so, to have it transparently launchable, it is sufficient:

• to install the full system to a directory;
• to add a dummy file called .no_centralized_system;
• to create 1 or more UAE configurations^example.

8. SINGLE-FILE APPLICATIONS

glUAE gives the possibility of launching any application in any form from a single file containing all the application files. This section demostrates how using the game All Terrain Racing, which comes on 2 floppy images.

The steps are:

1. creating a directory where to put all the files;
2. adding a UAE configuration^example that contains the settings for best compatibility/performance;
3. packing the directory to an LhA archive;
4. associating a project icon to the archive, with glUAE_ULA as Default Tool.

A complete installation would look like this:

The game can be launched with any method which directly addresses the archive.

A fundamental thing to bear in mind is that the archives are unpacked to a temporary location before execution, so any modification made by the applications affect only the temporary files, not the original archive. To preserve the changes (in this case, e.g. the high scores) all that is needed is to specify the script glUAE_ULASD ("Unpack, Launch Application and Save Data") in place of glUAE_ULA;

9. SPLASH SCREENS

For each application, glUAE allows to define a set of splash screens, which are shown upon launch by means of MultiView.
To define a splash screen it is sufficient to put an appropriately named file in the application directory.

There are 3 kinds of splash screens:

• the blocking splash screen: it blocks the launch of the application until it is closed; the file name is .blocking_splash_screen;
• the first-launch splash screen: it is like the blocking splash screen, but it is shown only the first time ever the application is launched; the file name is .first-launch_splash_screen
• the normal splash screen: it shows while the application loads and executes, and closes after the application quits; the file name is .splash_screen