	          ///    GRAND THEFT AUTO IV    ///
	    	 /// "ALICE" SCRIPTING PROJECT /// 
Histrory:
 Alice was the first project in the world what was related to
 Native-call engine in GTA IV ... 23d December 2008 ...

Version : 0.3.2

Change log:
 0.3.2 - added support for GTAIV v1.0.3 and 
         (!) disabled Alice working in MP game 
	 (MP support removed because of R* request)
	 (i hope that this is temporary)
 0.3.1 - added support of standart lua libs functions 
	 (base, table, io, string, math, debug)
 0.3.0.5 - rewrited some code for more performance and reliability
 0.3.0 - added high-level native-call constructions
 0.2.5 - supports patch 1.0.2.0 ,some bugs were fixed
 0.2.0 - added test support of CallSpecNative
 0.1.0 - 1st beta

1.What is Alice ?
  Alice is the gta iv script language engine parts binded
  to lua script language. 

  ps: There are many Lua manuals in the web.
      GTAIV.exe v1.0.1.0, v1.0.2.0, v1.0.3.0 are supported only

  Alice needs ASI Loader to run . (dsound.dll)

2.What about script files ?
  All(*.lua) scripts are running separetly and must be placed
  in "GTAIV\Alice" folder , scripts will not restart after
  save reloading , all of them is starting with the game .
  You can put examples in "GTAIV\Alice" folder and play now =)

3.General scripting information :
  GTA IV has many script functions called "Native API" or "natives".
  Alice lua script can call any of this functions from itself.

  -- General Alice scripting documentation --

  Old documentation is in "Old_versions" folder.

  There are two kinds of functions - quick and special:
  - Quick calls are using for a fast native execution, but u can't
    use them with natives what operate with models etc
    Quick call function name begins from "_" , so the function
    name'll be (for ex) _NAME .
  - Special calls are using for that natives what can't be
    executed with "Quick call".
    The name of the special is NAME, so it is like original
    and has no prefixes.

  Lua has no pointers so we must use lua-tables as pointers .
  Lets look for ex. into SpawnCar function in CarSpawner.lua:

  function SpawnCar(name)
    local p = {} -- let's declare PLAYER_CHAR table(pointer)
    GET_PLAYER_CHAR(GET_PLAYER_ID(), p) -- reading PLAYER_CHAR
					-- into p
    local PLAYER_CHAR = p.a -- reading "a" field from p into
			    -- local variable PLAYER_CHAR
			    -- "a" always contents int value 
                            -- "b" is float value
    if PLAYER_CHAR <= 0 then return end -- if char isn't valid
					-- we must exit
    local hash = GET_HASH_KEY(name) -- calculating car model hash
    REQUEST_MODEL(hash) -- loading this model
    while HAS_MODEL_LOADED(hash) == 0 do Wait(100) end  -- waiting
				-- until our model'll be loaded
    local x = {}  local y = {}  local z = {} -- decalring XYZ pointers
    GET_CHAR_COORDINATES(PLAYER_CHAR, x, y, z) -- reading player char 
					       -- coordinates
    GET_OFFSET_FROM_CHAR_IN_WORLD_COORDS(PLAYER_CHAR, 0, f(5), 0, x, y, z)
               -- game doesn't converts float<->integer, so if u 
	       -- wanna use int value as float u must use "f" func
    local c = {} -- declaring car handle pointer(table)
    CREATE_CAR(hash, x.b, y.b, z.b, c, true) -- creating car
 				-- we are using "b" float fields 
    PRINT_HELP(name) -- printing help via gxt key
    MARK_MODEL_AS_NO_LONGER_NEEDED(hash) -- unloading model
    Wait(2000) -- waiting a little
    MARK_CAR_AS_NO_LONGER_NEEDED(c) -- making car like random car
  end 	-- if native needs to read value from pointer,
	-- it reads "a" field 

 
   -- Player structure organization --
      int GET_PLAYER_ID() -- get player id , using only for getting
                          -- results of next functions
                          --  (always 0 in single player mode);
      int CONVERT_INT_TO_PLAYERINDEX( GET_PLAYER_ID() ) -- get player 
             -- index from id , this is player definition variable
             -- (in SA was $PLAYER_CHAR) (always 0 in single player mode);
      GET_PLAYER_CHAR( CONVERT_INT_TO_PLAYERINDEX( GET_PLAYER_ID() ), &PlayerChar )
             -- get player char from player index , this is "player as ped/actor"
             -- definition variable (in SA was $PLAYER_ACTOR);

   I wasted 2 days to fill free with lua coding , it's not so hard as you thought .

4. About :
    Authors : Alexander /Alexander Blade / Alexander Koryakin ,
	      flacs 
   THX 2 :    GooD, Listener, Seemann, Sacky, Lua developers, Katauri ...	

   http://Alexander.SannyBuilder.com
   http://OpenIV.com
  
   22:57 23.03.2009

    Alexander Blade 2008-2009 





