LuaBot, minor changes and description.

documentation/lua/luabot.desc.txt

@@ -0,0 +1,135 @@
+LuaBot is a trial and error script that exhausts the input-search-space by simply trying to push buttons. 
+
+You can program it to limit this searchspace, as it can become exponentially large. Just do the math. You can press eight possible buttons at any frame. That makes up for 8! or 8*7*6*5*4*3*2*1 possible combinations for one single frame. There are 60 frames in one second, that's 60 to the power of (8!).
+
+Anyways, the bot has two parts. The frontend, which we'll call BeeBee, and the Lua part, which we call LuaBot.
+
+You start the bot by openening the luabot_front.lua script file. Make sure the luabot_backend.lua file is in the same directory.
+
+BeeBee
+
+BeeBee (who received it's name from BasicBot, its predecessor) just writes it's contents into the LuaBot framework and produces a big Lua script for you.
+All you need to do is enter Lua code for the specific functions and the code will generate the script.
+
+You can also save and load the contents of the front-end. That way you can easily manage your bot scripts, without actually having to look into the LuaBot code.
+
+BeeBee is only a pasting mechanism. It does not compile Lua or warn for errors.
+
+LuaBot
+
+LuaBot is a generic trial-and-error script that serves as a bot framework. It will set inputs as you program them for a number of frames (called an attempt). When the isAttemptEnd() says the attempt ends, a new attempt is started. All the attempts fall under one segment. At the end of a segment (denoted by the isSegmentEnd() function), the best attempt is kept (judged by the score and tie functions) and the next segment is started. The bot is capable of rolling back if a segment runs into a dead end. This allows you to backtrack and restart a previous segment.
+
+The bot evaluates a true or false by checking to see whether the return value of a function is bigger then a certain value. It does this for EVERY function that returns something and every function that returns something must return a number (or Lua _will_ complain). For absolute true or false you can return "yes" and "no", "maxvalue" and "minvalue" or "pressed" and "released". Read variable info for more information.
+
+The script takes a number of variables and functions into account. Some variables become important to prevent desyncing over segments.
+
+- maxvalue
+The maximum value (exclusive) of the random evaluation. If a value is higher than rand(minvalue, maxvalue), it evaluates as true, else false. By default this is set to 100.
+
+- minvalue
+The lowest value (inclusive) of the random evaluation. If a value is lower than rand(minvalue, maxvalue), it evaluates to false, else true. By default this is set to 0.
+
+- yes / no
+- pressed / released
+These map to the minvalue/maxvalue.
+
+- loopcounter
+The number of times a frameadvance has been called by the main botloop.
+
+- key1 key2 key3 key4
+The input table of players 1-4. The keys are: A B up down left right select start. Set any to 1 if you want them to be set and to nil if you don't want them set.
+Note that these get cleared right before onInputStart is called. This variable is saved in a pseudo-movie table if the attempt is better then the previous one and used for playback when moving to the next segment.
+
+- lastkey1 lastkey2 lastkey3 lastkey4
+The inputs that were given to FCEU on the PREVIOUS frame. This holds for segments as well (at the beginning of a new segment, the lastkeys of the previous segment are set). This also goes for the start. If you use key1-4 in onStart, the first segment will have those keys as lastkey.
+
+- frame
+The number of frames of the current attempt. Starts at 1.
+
+- attempt
+The number of attempts in the current segment. Starts at 1.
+
+- segment
+The segment the bot is currently running. Note that rolledback segments are deducted from this number.
+
+- okattempts
+The number of attempts that have been deemed ok. This is a statistical variable. It might tell you how well your bot is doing (combined with the number of failed attempts).
+
+- failattempts
+The number of attempts in the current segment that have been deemed bad. This is a statistical variable. It might tell you how well your bot is doing (combined with the number of approved attempts).
+
+- segments
+This is the big table that holds everything together. Don't mess with it.
+
+- maxframes
+You can set maxframes and check it in the isAttemptEnd function to simply limit a attempt by this many frames. You can also just ignore this and do something else instead.
+
+- maxattempts
+Same as maxframes, except for attempts in a segment.
+
+- maxsegments
+Same as maxframes, except for segments in a run.
+
+- playingbest
+Will be set to true when the bot is playing back it's best attempt to advance to the next segment. Not really used by other functions.
+
+- keyrecording1-4
+A simple table with the pressed keys for playback.
+
+- X Y Z P Q
+Some "static" variables. These allow you to easily set them onStart and use them in various functions to return the same number. Like a global variable. The P and Q numbers used to denote a random number between 0 and P or Q, but they don't right now.
+
+- vars
+This is your variable table. It's contents is saved at the end of an attempt and will be loaded at the beginning of a segment. On rollback, this table is also kept. Put any variable you want to keep accross segments in this table.
+
+
+Ok. That's it for the variables. Now for functions. There are basically three types of functions. The functions that determine whether a button is pressed (8 for each player), to determine whether an attempt/segment/run has ended or was ok and functions for certain events. This number is not evaluated by the random-eval function.
+
+- getScore
+This returns how "well" the current attempt is. At the end of a segment, the best scoring good attempt will be used to continue to the next segment. In case of a tie, see the tie functions. This number is not evaluated by the random-eval function!
+
+- getTie1-4
+If the score ends in a tie, that is, two attempts score equally well (have an equal number of points for instance), you can use these functions to break that tie. Like, which attempt has the most health or is the fastest or whatever. This number is not evaluated by the random-eval function!
+
+- isRunEnd
+Return whether the bot should stop running. If the returned number is bigger then the random number rand(minvalue-maxvalue), the bot will stop.
+
+- mustRollBack
+Returns whether the bot should rollback the current attempt. In such case, the previous segment is loaded and the current segment is completely discarded. If the returned number is bigger then the random number rand(minvalue-maxvalue), the segment will rollback one segment.
+
+- isSegmentEnd
+If the returned number is bigger then the random number rand(minvalue-maxvalue), the bot will stop the current segment, play back the best recorded attempt and start a new segment. Mostly done when a certain number of attempts is reached, but possibly you know when have the best possible attempt and can move on.
+
+- isAttemptEnd
+If the returned number is bigger then the random number rand(minvalue-maxvalue), the attempt will stop and a new attempt will be started. Some examples when this function should return yes is when you reached a certain goal, a number of frames or when you died (in which case the bot should try again :).
+
+- isAttemptOk
+If the returned number is bigger then the random number rand(minvalue-maxvalue), the current attempt (which has just ended) is deemed ok. Only attempts that are deemed ok are up for being saved. For instance, when the player died in the current attempt, you should return no.
+
+- pressKeyX (pressKeyA1, pressKeyStart4, etc...)
+These functions determine whether a button should be pressed in the next frame. If the returned number is bigger then the random number rand(minvalue-maxvalue), the button is pressed, otherwise it is not. To absolutely press a button, simply return yes or no. To use some odds, return a number between minvalue and maxvalue. For instance, using the default settings, if you return 50, there is a 50% chance the button will be pressed.
+
+- onStart
+Maybe a little misleading, but the onStart function is called BEFORE the main botloop starts. You can do some non-generic startup stuff here like press start at the title screen and get the game started. Returns nothing.
+
+- onFinish
+The opposite to onStart, this function is called when the main botloop exits. You can cleanup, or write stuff or whatever.
+
+- onSegmentStart
+When a new segment is started, this is called. After initializing variables and such, but before onAttemptStart is called. Returns nothing.
+
+- onSegmentEnd
+When isSegmentEnd evaluates to true, this function is called. Returns nothing.
+
+- onAttemptStart
+Called at the start of a new attempt, after onSegmentStart (in case of a new segment) but before onInputStart. Returns nothing.
+
+- onAttemptEnd(wasOk)
+Called at the end of an attempt. The only function to have a parameter (note: case sensitive). The parameter wasOk will return (boolean) whether isAttemptOk evaluated to true or false. Returns nothing.
+
+- onInputStart
+In a frame, this is the first place where the key1-4 variables are cleared. This is called before all the input (pressKeyX) functions are called. Returns nothing.
+
+- onInputEnd
+This is called immediately after the input (pressKeyX) functions have been called. Returns nothing.
+

documentation/lua/luabot_framework.lua

@@ -1,20 +1,12 @@
 -- LuaBot, concept bot for FCEU and snes9x and any other emu that has compatible Lua engine
--- qFox, 30 July 2008
--- version 1.06
+-- qFox, 2 August 2008
+-- version 1.07
 
 -- Botscript data following:
 -- Rom: -- ROMNAME
 -- Comment: -- COMMENT
 -- Version: -- VERSION
 
-local function realcount(t) -- accurately count the number of elements of a table, even if they contain nil values. not fast, but accurate.
-	local n = 0;
-	for i,_ in pairs(t) do
-		n = n + 1;
-	end;
-	return n;
-end;
-
 local maxvalue = 100;    -- always "true", yes, pressed
 local minvalue = 0;      -- always "false", no, released
 
@@ -76,9 +68,6 @@ local Q = 0;
 
 local vars = {};              -- variable table. each cell holds a variable. variables are remembered accross segments
 
-local outputcounter = 0;
-local updateevery = 1000;
-
 -- user defined functions
 
 local function getScore()     -- score of current attempt
@@ -474,7 +463,9 @@ while (rand_if(isRunEnd())) do
 		-- also set the vars table to the table of the previous segment
 		if (segment == 1) then 
 			lastkey1 = startkey1;
-			lastkey1 = startkey1;
+			lastkey2 = startkey2;
+			lastkey3 = startkey3;
+			lastkey4 = startkey4;
 			vars = startvars;
 		else 
 			lastkey1 = segments[segment-1].best.lastkey1;

documentation/lua/luabot_front.lua

@@ -1,4 +1,6 @@
--- BeeBee, BasicBot Frontend v1.06
+-- BeeBee, LuaBot Frontend v1.07
+-- qFox, 2 August 2008
+
 -- we need iup, so include it here
 local iuplua_open = package.loadlib("iuplua51.dll", "iuplua_open");
 iuplua_open();