==============================
PS2 Lua Player - Introduction
==============================

Yes ! Finally we have a Lua Player for the PS2 ! This is a direct adaptation of
the PSP Lua Player, as my Goal was to enjoy all the PSP lua games available today
on my beautifull PS2 :)

Also, consider this first version as really Beta Software !

============================
What is Lua Player ?
============================
Lua Player is a script player for the Sony PS2. 
With it, you can run applications written in the language `Lua`. 
Writing Lua code is both faster and easier than writing for the PS2 directly.

============================
Player Status
============================

The current version is still in alpha stage, meaning that it STILL contains some
bugs, and won't run perfectly Please report bugs and problems in the following 
thread : http://www.psxdev.org/forum/viewtopic.php?t=141
This is a french forum, but you can post in english without any problems, and it
will help us to trace and correct issues with the player.

Following is the support status of the various PS2 devices :

- Host : working (using last version of ps2client/ps2link from SVN)
- MC   : working (both mc0 & mc1)
- USB  : working (using herben's usbhdfsd driver)
- HDD  : not supported
- CD   : since this is a read-only device, it's not officially supported.

Concerning Lua (the library) itself, the player misses some function correct implementation 
like the time function that are not fully implemented time(), difftime(),etc..
Some scripts using them will have to be modified in order to work properly.

============================
PSP Compatibility
============================

The PS2 player is based on the PSP API 0.20, meaning that virtually any game 
running on the PSP should work on the PS2.

However, as for the PSP player, the PS2 player relies on Lua 5.1.1, meaning that
some games won't run without some modifications (lua related)
The things you'll need to change for 5.1 (took from the PSP changelog) :
- change table iteration code:
  "for i, value in someTable do" to
  "for i, value in ipairs(someTable) do"
  (but use "pairs" for tables like "t={foo=bar, foobar=99}"
   and "ipairs" for tables like "t={foo, bar}")
- it's pure Lua 5.1: no binary operators and double as number type
   (e.g. now you can use one number for storing IP addresses)
   
Not all System functions are implemented (specially all the rmdir/mkdir/.. functions)

Pad button like "note" & "home" don't exist on the PS2, so script using it will not work,
(you'll have to remap them to others PS2 "compatible" buttons).

and for sure other little stuff that I might forgot...
   

============================
Function reference
============================
See doc/ for all functions and libraries that are specific to LuaPlayer.

============================
The LuaPlayer startup sequence
==============================

When LuaPlayer starts up, it will look for a script to load in the following
locations, and in the following order:
./luaplayer/script.lua
./luaplayer/[Application bundle or package]/index.lua
./luaplayer/[Application bundle or package]/script.lua
./luaplayer/System/system.lua

The provided system.lua script will execute the Lowser script located under the
Application directory

Additionally you can also execute a script by passing the script path to the
player as a parameter : 
i.e. : luaplayer.elf device:/path/script.lua


======================================
Making a Lowser-compatible application
======================================
Making your app play nicely with Lowser is very simple.
1. The main script file should be called "index.lua". Place it, with all its
   resources in a folder with the application's name (spaces and everything is 
   allowed; make the name nice: "Foobar's Magical Quest", not "foobar_game")
2. Instruct your downloaders to install your game in /luaplayer/Applications/
3. Make your game *exitable*, please. Just make sure that the end of the file is
   reachable. (Your main loop could look something like this:
	while not Controls.read():start() do
		[ your app's code ]
	end
)

note : respecting to the orginal version I swaped [O] and [X] buttons, so that
       [X] is actually used to select an app/dir and [O] to go back to the upper 
       directory.


============================
Credits
============================
Herben          - help
Paulo35         - help and debugging
Tmator          - for hosting my blog and the Froggies website !
gawd            - for spiritual help with audsrv :)
Frank Buss      - Wrote the original PSP Player and on which this work is based