TUTORIAL: Virtual AGS Development Workstation on Linux

[RickJ]

Introduction

This tutorial explains how to setup an AGS Development Workstation on a computer running the Linux operating system.  This will be accomplished by creating a virtual machine in which Windows XP and AGS will be installed.  Here is a screen shot of the test system showing the AGS editor and a test game running on a Linux desktop under KDE 4.3.

This tutorial is divided into several sections so that it's easier to read and so that the tutorial may be completed in multiple sessions over a period of time rather than all at once.

 - Install linux
 - Post Installation
 - VirtualBox Installation
 - Windows Installation
 - Setup AGS Game File Storage Area
 - Install AGS and other Software on Windows
 - Using the AGS Workstation

System Requirements
The two most important resource considerations in setting up a virtual windows machine is CPU speed and Memory size.  The relevant specifications of the computer used to test this tutorial are as follows:

Linux Version:	Kubuntu 9.10
CPU:	2.5 GHz AMD 64-bit Dual Core
Memory:	2 GB
Hard Drive:	Seagate 500 GB SATA II

With the above system there were no observed performance problems.  One would speculate that the minimum requirements would be something like those listed below and that such a minimal system may exhibit some undesirable performance characteristics.

Linux Version:	Kubuntu or  Ubuntu
CPU:	1.5 GHz single core
Memory:	1 GB
Hard Drive:	150 GB

Sumary:
Using a virtual machine to run the AGS Editor and other windows applications,  commonly used in the game making process, is trouble free, mostly eloquent and easy.  The only down side is that a  system with enough Cpu and memory is required.  Fortunately most current PC offerings exceed the requirements and will suffer no performance problems.  The same cannot be said for computers that are 5-10 years out of date.

Todo
  2009-00-00  write "Using AGS Workstation" section

Tutorial Revisions
   2009-10-23  remove alternate user management method, no longer necessary
   2009-10-19  add desktop screen shot
  2009-10-17  publish original version

[RickJ]

Linux Installation (Kubuntu 9.10)

The Linux version of the AGS runtime is built using Ubuntu linux so using one of the flavors of Ubuntu is a good idea. Ubuntu uses the Gnome desktop environment and is comfortable for people who are accostomed to using Windows XP.  Kubuntu uses the KDE desktop which has many advanced features and so is preferred by many power users.  Since I prefer Kubuntu this document will describe how to setup an AGS workstation on Kubuntu.

Create Install CD
To install Kubuntu Linux download the install disk iso image and burn it to a CD. The Kubuntu and Ubuntu install disks can be found at the following ebsites:

 http://www.kubuntu.org/
 http://www.ubuntu.com/   

Put the install CD in the drive and reboot the machine.  After selecting a language will be given a choice to run Kubuntu right off the CD or to install it.  Check it out first if you like and then proceed  with the installation when you're ready.

Start Installation
The Kubuntu installation will ask you to supply basic configuration information as shown below.  Just follow the straight forward instructions and fill in the requested information appropriately.  

 - Language
 - Time Zone
 - Keyboard
 - Disk Setup
 - User Info

Partition Hard Drive
The disk setup screen asks the user to select a disk drive on which to install kubuntu and then gives options to use the entire disk, to use the just the empty space, or to manually partition the disk.  If windows is installed on another disk or another partition then Kubuntu will install along side  windows and a boot menu will provide the ability to select either OS.  If a dual boot system is desired it is easier (and safer to the existing windows installation) to install linux to a new or second hard disk that can be wiped clean without consequence.

It is recommended that the disk partitions be setup manually so that there are two partitions and a swap area rather than the default of one partition and swap area. Having two paritions allows the executable programs to be seperated from user data.  In this way a the linux installation can be completely replaced without losing or otherwise affecting the users' data.

On the test system the 500GB drive was partitioned  as shown in the table below.  The default swap space seems to be about 6Gb which was increased to 10Gb.  It is not known what affect, if any,  this will have on system performance.

Mount	Type	Size MB	Description
/	ext4	154998	programs and operating system
/home	ext4	330096	user data
swap	swap	10001	virtual memory

Finish the Installation
The home partition is bigger than the root partition because this is where a 20-50Gb virtual disk drive will eventually reside.  Once the partitions are setup to your satisfaction proceed with the installation which will take about a half hour.

[RickJ]

Post Installation

After the initial installation is complete additional software is typically installed.  There is a nice guide online at the url below that explains how to customise Kubuntu and install just about everything that is avaiable.  Much of the information in this document is derived from this guide.

  http://kubuntuguide.org/

Switch to Classic Menu
The instructions in this document  refer to the classic menu so it is recommended that it be used to perform the operations described below.  Don't worry it only takes two clicks to change from the modern menu and the  classic menu and back again. 

  - Right click on the Kde "K" icon at the left end of the task bar
  - Select "Switch to Classic Menu Style
  - Click the Remove button on the dialog box that pops up

Open Console Window
Open a console window so that you have easy access to the command line. If you are instructed to enter a command in the console you can just copy the text from this document and paste it into the console's command line. 

  K->System->Konsole

Enable Proprietary Drivers (video)
Click on the Kde "K" icon to open the main menu and select:

  K->System->Hardware Drivers
 
From the popup dialog box activate the recommended drivers for the hardware on your system.  On the test system the recommended NVIDIA driver was selected and then the activate button clicked.  This takes a few seconds to complete.  The new drivers will typically be loaded the next time the system boots up.

Install Firefox
The default web browser in Kubuntu is Konqueror.  Konqueror is a great file manager (used to be better in KDE 3.5) and is an ok web browser but most people prefer to use Firefox .  Kubuntu 9.10 has a convenient Firefox installer that makes Firefox installation very easy.  Just select the installer from the menu and follow the on screen instructions.

  K->Internet->Install Firefox

Update Installation
Open the KDE control panel from the main menu.  From the control panel window select the Add/Remove Software icon.  A new window will open.  Select the "Software Updates" icon.  Wait for update scan to complete then  click "Select All" button and the "Apply" button.

  K->Settings->System Settings
  Kde Control Panel->Add/Remove Software
  Add/Remove Software->Software Updates
  Add/Remove Software->Select All
  Add/Remove Software->Apply

Alternatively you can enter the following commands on the command line in the console window.  For those who are comfortable using the console this can be the easiest and fastest way of doing things.

  $ sudo apt-get update
  $ sudo apt-get upgrade
  $ sudo apt-get dist-upgrade
 
Add Restricted Extras
For historical, ideological and legal reasons most Linux distributions are loathe to include any kind of proprietary software in their default install.   The do however make easy (some distribution make it easier than others) to install additional proprietary software such as hardware drivers, flash players, and the like.  The Kubuntu Restricted Extras package contains software such as Sun's JRE, multimedia codecs, MS core fonts, flash plugin for Firefox and other browsers and more.   Enter the following commands on the console's command line to install:

  $ sudo apt-get install kubuntu-restricted-extras

Install Other Desired Software
Take some time and explore the extensive software catalogue that is available for Kubuntu.  Select K->Settings->System Settings from the main menu to open the control panel.  Select Add/Remove programs from the panel to open the package manager.  Install any additional packages that may be of interest to you. 

Note: As of this writing there has been a change to the "Add/Remove Software" control panel.  It used to show main applications only along with a brief description of the application.  It now shows a list of all packages including libraries and other supporting packages and no description.  IMHO this makes it very confusing for anyone wishing to try new and different applications.  Hopefully this is only a temporary situation that will be corrected in the near future.

[RickJ]

Virtual Box Installation

Virtualbox is a virtualization software that allows the user to create a virtual machine upon which a guest operating system, such as WinXP, may be installed.  To install VirtualBox open the  Add/Remove software module on the control panel from the main menu as follows

 K->Settings->System Settings->Add/Remove Software

Enter "virtualbox" in the search window.  You will see either one package or a list of packages.  If there is a list then select the following packages and then click on the "Apply" button to install the packges.

 virtualbox-ose
 virtualbox-ose-qt
 virtualbox-ose-source
 virtualbox-guest-additions

Create the Virtual Machine
Open the Virtualbox control panel from the main menu as follows:

 K->Utilities->VirtualBox OSE

Now click on the "New" icon to open a wizard that creates a virtual machine.  Enter the following information on the various screens that appear.  

 VM Name and OS Type
 ==================================
 Name: WinXp
 Operating System: Microsoft Windows
 Version: Windows XP

 Memory
 ==================================
 Memory: 640 MB

 Virtual Hard Disk
 ==================================
 Boot Hard Disk: Yes
 Create New hard Disk: Yes

 Hard Disk Storage Type
 ==================================
 Dynamically Expanding Storage: Yes

 Virtual Disk Location and Size
 ==================================
 Location: /home/username/vbox/WinXP
 Size: 25GB

Click on the "Finish" button to create the virtual machine.  

Create Desktop Icons
The next thing I would recommend is to create a couple of desktop Icons to start and stop the VM.  In this way it won;t be necessary to use the VirtualBox controls panel found on the main menu at:

 Utilities->VirtualBox

The first thing to note is that there is a command line interface called VBoxManage that allows VMs to be controlled from a  command line.  The following two commands are used to start and stop our VM.

 $ VBoxManage startvm  WinXP
 $ VBoxManage controlvm WinXP poweroff

The Kubuntu destop environment, KDE 4.3, uses a different desktop paradigm in that the desktop contains widgets, (mini-applications) rather than traditional icons.   Fortunately there is a widget called Folder View that provides the same (and more) functionality as traditional desktops.  In fact folder view can be used to emulate the traditional desktop environment.  Just right click on the desktop and select "Desktop Settings" from the context menu.  In the dialog box that pops up, change Tyoe from Descktop to  Folder View.

If you don't have a Folder View of your Desktop folder then create one by right clicking on the desktop and selecting "AddWidget" the following from the context menu.  A dialog will appear with a list of widgets.  Scroll down the list, select Folder View and press the Add Widget button.  

A folder view widget should appear on the desktop. Right click inside the Folder View widget, select Folder View Settings and check the "Show Desktop" radio button. You should now have a Folder View of your Desktop folder.

Now we can create our Start/Stop icons.  Right click in folder view and create a new application link from the context menu as shown below.

 RightClick->Create New->Link to Application
 
Right click on the newly created icon and click on the application tab. Fill in the information as follows:

 Name: Start WinXP
 Description: Start WinXP Virtual Machine
 Comment:
 Command: VBoxManage startvm WinXP
 Work path: /home/ags

Click the OK button and then right click the icon once more.  This time click on the General tab and enter the name text from above, WinXP-Ags Start VM, into the text entry field.  Now click on the icon to change it'sgraphic.   Select the "Other Icons" radio button and scroll to find the virtualbox  graphic. Select it and press the OK button.

Repeat the process to create the Stop WinXP-Ags icon using the following information:

 Name: Stop WinXP
 Description: Stop WinXP Virtual Machine
 Comment:
 Command: VBoxManage controlvm WinXP poweroff
 Work path: /home/ags

Assign User Groups
The installation process has created a "vboxusers" group.  We are going to create another group called "agsdev".  We are then going to make our user account a member of both groups.  Open the control panel from them main menu and navigate to the User Management control panel.

 K->Settings->System Settings
 System Settings->Advanced->User Management

Now, add the following two groups to your system and make your username a member of those groups.  The group "vboxusers" should already be present, if not then create it.

 vboxusers
 agsdev

[RickJ]

Windows Installation

Windows XP (SP3) is recommended but you can of course install any version of windows you wish.  Just be aware that earlier versions may lack the .Net framework, drivers, or other essentials and later versions are said to be resource hungry.

In the VirtualBox control panel select the newly created VM.  Put the windows installation disk in the CD/DVD drive and click on the settings icon  to open a "Settings" dialog.  Select CD/DVD ROM and enter the following information:

  Mount CD/DVD Drive: Yes
  Host CD/DVD Drive: Yes
  Selected Drive: {drivecontaining windows disk}
  Enable Pass Thru: yes

In the VirtualBox control panel click on the "Start" icon to begin the windows installation process.  Follow the usual windows installation process. 

Install Guest Additions
Guest Additions is a VirtualBox helper software that is installed on the windows guest operating system.  It allows the mouse cursor to move freely between host operating system windows and guest operating system windows, negating the need to use the Right-Control key to make this transition.  It also allows the guest operating system to run in "seamless" mode.  To install
Guest Additions use the main menu at the top of the virtual machine's window and select the following:

  Device->Install Guest Additions

Follow the on screen instructions to complete the installation.  When the installation is complete WinXP will need to be rebooted.  Click the "Reboot Now" button.  After WinXP reboots you will be informed that the cursor will no longwer be captured. This means that the mouse cursor will be able to freelymove to/from windows' applications  to/from linux applications without pressing
the right-control key.

Enable Seamless Integration
Windows XP should now be running in a Linux window.  You may now turn on seamless integration by making the selection below from the virtual machine's main menu:

  Machine->Seamless Mode

The virtual machine window should disappear leaving you with only a windows task bar at the bottom of the screen.  According to the documentation you should be able to switch out of seamless mode by pressing the 'L' and Right Control keys at the same time.

[RickJ]

AGS Game File Folders

By default Ags will create and save it's game files on the Windows virtual disk. The problem with this is that Linux applications will not be able to access the virtual disk.  However, both Windows and Linux applications can access the Linux file system.  So what we want to do is to create some folders on the Linux file system for this purpose.  Here is a directory structure commonly used by
many AGSers.  You may of course modify it to meet your own needs and work flow habits.

   /home
      |
      +--ags
             |
             +--bin           {shell scripts}
             |
             +--lib            {commonly used resources, fonts, sounds, etc}
             |
             +--archive     {released versions of games, zip files}
             |
             +--2.72         {game files edited with AGS 2.72}
             |
             +--3.10         {game files edited with AGS 3,10}
             |
             +--3.20         {game files edited with AGS 3,20}

Create AGS Folders
Now we can create the above folders.  First open a console window if you have not done so already.

   K->System->Konsole

Now enter the following commands in the console window to create the folders.

   $ sudo mkdir /home/ags
   $ sudo mkdir /home/ags/bin
   $ sudo mkdir /home/ags/lib
   $ sudo mkdir /home/ags/archive
   $ sudo mkdir /home/ags/2.72
   $ sudo mkdir /home/ags/3.12
   $ sudo mkdir /home/ags/3.20

Now change the group assignment of these folders. We will put thes folders in the agsdev group so that any users who are members of this group may have access to them.  Entering the following commands in the console window will accomplish this.

   $ sudo chown root:agsdev /home/ags
   $ sudo chown root:agsdev /home/ags/bin
   $ sudo chown root:agsdev /home/ags/lib
   $ sudo chown root:agsdev /home/ags/archive
   $ sudo chown root:agsdev /home/ags/2.72
   $ sudo chown root:agsdev /home/ags/3.12
   $ sudo chown root:agsdev /home/ags/3.20

Now change the file permissions of these folders so that members of the agsdev group will have read and write access to files that reside in these folders.    Change the file permissions by entering the following commands in the console window.

   $ sudo chmod 774 /home/vbox
   $ sudo chmod 774 /home/vbox/winxp-ags
   $ sudo chmod 774 /home/ags
   $ sudo chmod 774 /home/ags/bin
   $ sudo chmod 774 /home/ags/lib
   $ sudo chmod 774 /home/ags/archive
   $ sudo chmod 774 /home/ags/2.72
   $ sudo chmod 774 /home/ags/3.12
   $ sudo chmod 774 /home/ags/3.20

Setup Shared Folders
To setup the shared folders the virtual machine must be stopped.  If you setup desktop icons to control the VM you can just click on the Stop icon, otherwise just select the following from the Windows Start Menu:

   Start->Turn Off Computer->Turn Off

Now open the VirtulBox control panel from the Linux main menu by selecting the following:

   K->Utilities->VirtualBox OSE

From the control panel open the Settings dialog box by clicking on the "Settings" icon.  Select the "Shared Folders" tab and then use the "Add new folder"  icon to add the following shared folders:

   Shared Folders:
      Add Folder:
         Folder Path: /home/ags
         Folder Name: ags
         Read-only: no
      Add Folder:
         Folder Path: /home
         Folder Name: home
         Read-only: no

Now start the windows VM by clicking on the Start icon in the VirtualBox control panel.  When Windows completes it's boot process open the windows file manager.   

   Start(right click)->Explore

In the directory tree pane of the file manager scroll down to the "MyNetworkPlaces" node and expand it. Now expand the "Entire Network" and "VirtualBox Shared Folder" nodes.  You should see something like this:

  MyNetworkPlaces
      |
      +--Entire Network
               |
               +--Microsoft Windows Network
               |
               +--VirtualBox Shared Folders
                       |
                       +--\\VBOXSVR\ags
                       |
                       +--\\VBOXSVR\home

Now map the shared folders to network drives. Right click on the shared folder and select "Map network drive" from the context menu.  Supply the following information to the dialog that pops up.

   \\VBOXSVR\ags (right click)->Map Network Drive
      Drive: Z
      Folder: \\VBOXSVR\ags (grayed out)
      Reconnect at logon: Yes

   \\VBOXSVR\home (right click)->Map Network Drive
      Drive: Y
      Folder: \\VBOXSVR\ags (grayed out)
      Reconnect at logon: Yes

Alternatively you can execute the following commands from the Windows command line:

   net use Y: \\vboxsvr\home
   net use Z: \\vboxsvr\ags

[RickJ]

AGS and Other Windows Software Installation

The first thing we need to do is to download and install the current version of
the .NET framework from Microsoft.  Download from the following URL and run the
installation program.

  http://www.microsoft.com/Net/Download.aspx

Install AGS
The current version of Ags can be downloaded from the following URL. There is usually a beta version available in the Technical forum if you like to be on the bleeding edge.

  http://adventuregamestudio.co.uk/acdload.htm

Start the installation program and follow the on screen instructions to install AGS as you normally would.  Then Startup the AGSEditor and open the "Preferences" dialog box by making the following selection from the main menu.

 AGSEditor->Preferences

Now enter the following information in the "New Game Directory" section, where X.XX is the version of the AGS editor that is being run.  I'm not certain if this setting is global for all editor versions or if it is version specific.  If not perhaps this should be a suggestion.

 Defaults to: Z:\X.XX

Install Other Windows Software
Now you may install any other windows software you like.  Below are a few recommendations that that you may find interesting or that may come in handy while working with AGS.

  Firefox                 http://www.mozilla.com/en-US/firefox/ie.html
  7-Zip                    http://www.7-zip.org/
  Graphics Gale      http://www.humanbalance.net/gale/us/index.html
  Cubic Explorer     http://www.cubicreality.com/
  Audacity              http://audacity.sourceforge.net/
  AutoIt                 http://www.autoitscript.com/autoit3/
  Wink                   http://www.debugmode.com/wink/

[RickJ]

Using the Virtual AGS Workstation

Under Construction

[Pumaman]

Looks very thorough, nice one

[xenogia]

Nice work, I already do this under Ubuntu 9.04 and it is a good alternative.  Hopefully soon Wine gets .NET framework working correctly and that would be even better since the AGS runtime engine works perfectly under Wine.  Even better, maybe one day a MONO implementation of the AGS editor.  But in due time I guess.

[RickJ]

Would  one of the mods consider moving this to the "Module, Plugin, Tech FAQ" forum before it goes into the bit bucket. 

[Dualnames]

Would  one of the mods consider moving this to the "Module, Plugin, Tech FAQ" forum before it goes into the bit bucket. 

Gee, seconded. I just noticed this. I'm not much into Linux, but I've read it and it's totally thorough and explainatory. Greatest of jobs there RJ!

[GarageGothic]

Wow, skimming through this and seeing what kind of hoops Linux users have to jump through really makes me forgive Vista its shortcomings. Excellent tutorial!

[xenogia]

Linux is great, I only stopped using it after a year because I needed Windows for After Effects and some wondering gaming.   I really couldn't have bothered with dual booting to be honest.

[Peter Bear]

Hello RickJ

I use AGS editor with a windows xp virtual box, I only experience a little trouble in this ...

the compiled game wont launch in full screen ( ctrl  + F5 ) why ?
Thank you

[RickJ]

To the best of my knowledge this is what happens:  In full screen mode AGS attempts to set the resolution of the graphics card.   Programs running inside the virtual machine don't have access to the actual hardware and so AGS fails  it's attempt. 

I use one of the filters x2 or x3 to make the test window large enough to see on my screen.

[xenogia]

Is there an easier to load up the saved source in wine instead of pressing f5 in the AGS IDE.  This way the game runs a lot faster for me.  Any ideas?

[Abisso]

I'm a Kubuntu user as well, version 10.10 right now. I found this tutorial so useful and this topic so interesting that I want to contribute with my experience as well.
If you're unsure if you're gonna try Vbox, don't be scared by the apparently long and complicated instructions Rickj wrote: if you take time to read them, you'll notice half of it is just to install Kubuntu, and the whole guide is written in the most precise and attentive way possible. If you have a linux system already installed and working, the whole process is very easy and just takes about 20 minutes + the time needed to install winxp and Ags (like you would on a physical PC).

First of all: the specs for the virtual machine suggested by RickJ worked perfectly fine for me with a physical machine older than Rickj's one (Intel E6300 1,87 Ghz, 2 GB RAM). My system shows about 700 MB of shared memory allocated (instead of the 640 expected), but just 45 MB of actual memory used, with ags running on a virtual winxp (sp3). Really not much, and I don't notice any slowdown in winxp nor kubuntu with normal use of both. Internet connection was set up automatically and worked fine.

GuestAdditions: the installation of GuestAdditions is very useful and recommended, but beware:

1. Clicking on the Virtualbox's taskbar -> Devices -> Install Guest Additions actually just mounts an .iso in the cd-rom drive. So you have to open My Computer after that, and double-click on the cd-rom drive to begin the installation. I don't mean to offend anyone with such a simple suggestion, and I'm sure most users would have figured this out by themselves, but even I honestly expected the installation to begin AS SOON AS I clicked on "Install Guest Additions".

2. The "mouse integration" feature (the one that captures mouse cursor as soon as you move on your virtualbox window) can cause some problems with your games. In my game, I have an interface which works this way: you right-click on something and then a GUI pops up and stays on screen until you click on something over that or move the cursor off of it. Unlike the MI3 verbcoin, you don't have to keep the mousebutton pressed all the time. Anyway, with the "mouse integration" enabled the interface didn't work as intended: the GUI stood on screen only as long as I kept the mousebutton down, and I couldn't move the cursor at the same time, so it was useless.
So, I guess  the mouse integration may cause other issues as well.
Luckily, you can enable and disable it in a matter of seconds. Just go on the VBox taskbar -> Machine -> Disable Mouse Integration and do the same to reactivate it. I suggest you keep it activated, as it's really useful, but in case you get strange responses from an application, try to deactivate it before you go mad searching for bugs in your code.

Seamless mode: as Rickj said, another really useful feature of Vbox is the Seamless Mode: you find this option in Machine -> Make Seamless.
Not only you can work fullscreen with it, but you only see the windows taskbar if no program is open in the virtual operating system. It's harder to explain than to use, but it really changes your experience with Vbox. See it for yourself. Mind that, when you're in seamless mode, the Vbox taskbar is hidden and only shows up if you hover the mouse on the central-bottom portion of the screen. And mind that some of the options listed in the submenus (Machine and Devices) are hidden as well, until you disable Seamless mode (right-ctrl + L , by default).

Shared folders: if you're not too familiar with Linux: don't be scared by what RickJ suggests about the shared folders: his approach is simply the most correct and reasonable one (creating separate groups and folders organized rationally). But the truth is, if you're lazy, you can simply create a folder inside your profile (/home/your_name/folder_name). Then you open Vbox, click on Settings -> Shared Folders -> Add Shared folder, and then select the folder you've previously created and click ok. On your virtual winxp then, you can go to My Computer -> Tools -> Map Network Drive and then select the drive letter you prefer and the folder you created. Make sure "reconnect on logon" is checked and click ok. Et voilà. You can now access that folder as usual, from My Computer.
A suggestion: call the shared folder with a short simple name: some characters aren't allowed and maybe a long folder name is unsupported as well. Just stay away from trouble, and call it "xpshared" or something like that.

Last, but not least: compared to opening them with wine (ver1.3) AGS games run a lot better: in fact, I can't see any difference when I run them on a real winxp installation. With wine instead, there are some games that run significantly slower and are almost unplayable (just some, the majority runs fine as well). Only issue, that's already been pointed out and I'm gonna confirm, is that Fullscreen mode doesn't work. I suggest you work fullscreen with Vbox and play/test ags games in windowed mode, maybe following Rickj's suggestion to use a filter to enlarge the window, if needed.