--- /dev/null
+HOWTO.txt: A beginners guide to entering the UCC::ProgComp 2010.
+
+If you get stuck at any point, consult, in this order:
+ - documentation for the ProgComp
+ - Google
+
+=== Setting up a development environment ===
+
+The ProgComp will work best for those running Mac OS X or Linux, but Windows is also supported.
+
+All competitors will need Python, a modern, object-oriented scripting languages. Python comes pre-installed on Mac OS X and modern Linuxes - Windows users must download it from http://www.python.org/download/releases/2.7/
+
+Then software you'll then need depends on the language in which you wish to program. The most up-to-date details, including some useful links, can be found at http://progcomp.ucc.asn.au/FAQs under "What software do I need to enter?"
+
+Set up the relevant software now - we'll assume you have it working in the rest of this document.
+
+=== Trying out the sample agents ===
+
+Full sample code is supplied for all the supported languages.
+
+Pull up a terminal/command line prompt. Change directory to the src/ subfolder (*nix path conventions will be used throughout) and type "python simulate.py -v"
+
+You should see some output as "Angel", "Lucifer", "Streetfighter" and "Wash", the 4 sample agents, battle it out. If you an error is raised, well, that's a bit awkward. It's probably due to your python installation - check that, check the FAQs, then google the error message, then if none of that works, contact us.
+
+If you're using Python, take some time to poke around at SampleAgents.py, then skip to the next section.
+
+If you're using C/C++, Java or MATLAB, follow the instructions in the src/link/<language> directory to get those agents running. Again, if something goes wrong, check the documentation, the FAQ, Google, and then if still stumped, contact us.
+
+Take some time to poke around at the sample code and get a handle on what's going on and how it works.
+
+=== Making your own ===
+
+Here's where you have to do the thinking. Your agent must consist of a single source file, and provide the same function definitions as the sample agents.
+
+<<standardise location for agents?>>
+Put your code in the "agents/"
+
+Information about creating the relevant python wrapper script to allow your program to interface with the supervisor should be provided with the sample code for your language.
+<<FIXME>>
+
+=== Submitting your own agent ===
+
+Procedures for submitting your own agent will be released by email and on the website soon. Stay tuned.
+
+Submitting your agent is not the end of the fun, either. All going well*, there should be a running leaderboard, so you can watch your agent compete, if you wish, or you can keep its runnings secret until the final judgement.
+
+* This includes the organiser not dying of a caffeine overdose or developing a psychiatric injury as a result of overloading and co-ordinating. Your mileage may vary. UCC members may donate to the coke account 'dja' if they wish to keep me supplied with coke and pizza during this time.
\ No newline at end of file
--- /dev/null
+INTERNALS.txt: Needless information about the internals
+
+This document is unreliable, out of date and more than likely, utterly useless. But it's included anyway.
+
+=== Notes originally found in src/README ===
+Contributor instructions:
+
+BaseAgent, LearningAgent and Supervisor are all implemented in uccProgComp.py.
+The 'select' algorithm, responsible for choosing agents for battle and
+determining when a round is finished, is the hottest part of the code and the
+most open to discussion and change.
+
+Unfortunately, it is not an easy bit of code to understand. Once upon a time,
+in builds long past, it used friendly O(n) operations and conveniently wasted
+memory on simple tasks. After hours of profiling, it is a little more complex,
+but with a bit of background to how the supervisor operates you shouldn't have
+much trouble working out the rest:
+
+1.) A copy of the current population list is made at the beginning of the round
+representing the agents who can still fight. This reduces finding valid agents
+from O(n) to O(1). I call it the 'remaining' list.
+2.) Agents must remember their index in the population list. This is because it
+would be O(n) to determine their index in the population list (to remove them
+when they die) from their index in the 'remaining' list. Agents have this value
+stored at the beginning of the round - O(n) at the beginning of the round is
+far preferable to O(n) for every death.
+3.) The actual removal of agents from the population list must happen all at
+once in reverse numeric index order at the end of the round so that the stored
+index that agents have does not become stale.
+
+There are problems. It's not perfect, but it's relatively fast and powerful and
+quite easy to adjust or reimplement once you get your head around it. I'm very
+much open to suggestion for improvement (especially in the form of patches) and
+welcome all help, constructive criticism, derisive criticism and death threats.
+
+Things to be done:
+
+1.) Pretty graphs! Iterate () returns a collection of statistics about each of
+the classes, which can be seen used in simulate.py. There are plenty of
+plotting packages out there that can turn this information into impressive
+charts.
+2.) More built-in functionality for BaseAgent and LearningAgent. They could
+both do with a few more utility functions for competitors to use.
+3.) A more succint set of rules and documentation.
+
+Thanks for reading!
+Luke
--- /dev/null
+JUDGING.txt: An insight into the capricious and arbitrary mind of the organiser on how your agent will be judged.
+
+<<FIXME: check this is accurate and OK to publish>>
+
+IN SUMMARY: write clean, efficient, portable, smart code that just does what it's told and doesn't try to do anything it shouldn't. Don't rely on *anything* not expressed in sample code, or preferably, documentation. If in doubt, ask.
+
+THINGS NOT TO DO:
+ - Inline assembler.
+ - Deliberately obfuscated code.
+ - Attempts to communicate between bots.
+ - File, network or system access.
+
+Other points:
+
+There are lots of divisions. Each division has its own prizes. How many divisions there are, and what the prizes are, depends on how much we get sponsored, and how creative I am at the time.
+
+Be honest in the divisions you sign up for, and don't play silly games. Trying to break the software, security, machines, my mind, etc., are all frowned upon and may result in instant disqualification, etc., as laid out in the rules.
+
+To win the most prizes:
+ - Allow your agent to be run on the scoreboard: I might give a prize to top-of-the-ladder agents.
+ - Make your agent as fast and efficient as possible - there might be *lots* of instances.
+ - Don't rely on points tables too much. I am interested in how agents perform in different situations - like a zero sum arena for example. If I ever get around to looking at this I will make it possible for your agent to query the points table.
--- /dev/null
+Copyright (c) 2008 Luke Williams
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
--- /dev/null
+=== UCC::ProgComp 2010 ===
+
+Congratulations, you've found the documentation!
+
+ - WELCOME.txt: A general introduction to the competition.
+ - HOWTO.txt: A guide to getting the software you need to compete, and making your first baby steps towards competing.
+ - JUDGING.txt: An insight into the capricious and arbitrary mind of the organiser on how your agent will be judged.
+ - http://progcomp.ucc.asn.au/Rules : the rules of the competition
+ - http://progcomp.ucc.asn.au/FAQs : Frequently Asked Questions
+ - http://progcomp.ucc.asn.au/More%20Info : General Info
+ - NOTES.txt: possibly important stuff that doesn't fit anywhere else.
+ - INTERNALS.txt: Internal information which might interest you but which you shouldn't rely upon.
+ - UNSUPPORTED.txt: How to use a language that isn't Python, C/C++, Java or Octave/Matlab.
+ - LICENSE: the terms under which the code is released to you.
\ No newline at end of file
--- /dev/null
+UNSUPPORTED.txt: You should not need this file.
+
+Consult the website.
+FIXME: more info?
\ No newline at end of file
--- /dev/null
+Welcome to UCC::ProgComp 2010!
+
+This document will acquaint you with the competition: the rules, how to write an agent, and what you need to do to enter.
+
+=== What is UCC::ProgComp? ===
+Good question! The facetious answer is that it's the package whose documentation you are currently reading. The long answer is that it's a project of the University Computer Club (UCC), a student club affiliated with the Guild of Undergraduates at the University of Western Australia. UCC::ProgComp is designed to raise interest in programming and raise awareness of what UCC offers.
+
+=== Why should I enter? ===
+For a number of reasons:
+ - there are prizes.
+ - it's a low-risk opportunity to learn how to program or to practise your programming. You don't need to be an expert to enter, and it's a great way to do things that you might not otherwise get the opportunity to do.
+ - To meet other computer-oriented people around UCC.
+
+=== What's the basic premise? ===
+Entry in UCC::ProgComp is by writing an agent that plays a modified version of Rock-Paper-Scissors on the morally bankrupt underworld of RPS Island.
+
+On RPS Island, this classic game is considerably more complex: the attacking agent must bluff to the defending agent before making its real attack. Agents receive a moderate rewarded for being nice to each other and going for a mutually beneficial tie, but receive the most points for stabbing the other in the back.
+
+An agent consists of a Python, C/C++, Java or MATLAB file with 3 functions:
+
+ * A function to attack another bot.
+ * A function to defend itself against another bot.
+ * An optional function to receive the results of its battle, so that it can learn how other agents play.
+
+=== OK, how? ===
+Keep reading! Read HOWTO.txt, then go to README.txt to see what other documents are available.
+
+=== I've read everything and I'm still confused! ===
+Firstly, check the FAQs at http://progcomp.ucc.asn.au
+If you're still stumped, contact us via the link at http://progcomp.ucc.asn.au
\ No newline at end of file
+++ /dev/null
-Copyright (c) 2008 Luke Williams
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in
-all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-THE SOFTWARE.
+<<PLEASE SEE THE CONTENTS OF doc/ FIRST>>
+
Hi there,
Thanks for taking interest in the UCC Programming Competition 2010. If you
...and if all you're interested in is participating, that's it! You can stop
reading, and start work on the agent that will outsmart them all!
-Contributor instructions:
-
-BaseAgent, LearningAgent and Supervisor are all implemented in uccProgComp.py.
-The 'select' algorithm, responsible for choosing agents for battle and
-determining when a round is finished, is the hottest part of the code and the
-most open to discussion and change.
-
-Unfortunately, it is not an easy bit of code to understand. Once upon a time,
-in builds long past, it used friendly O(n) operations and conveniently wasted
-memory on simple tasks. After hours of profiling, it is a little more complex,
-but with a bit of background to how the supervisor operates you shouldn't have
-much trouble working out the rest:
-
-1.) A copy of the current population list is made at the beginning of the round
-representing the agents who can still fight. This reduces finding valid agents
-from O(n) to O(1). I call it the 'remaining' list.
-2.) Agents must remember their index in the population list. This is because it
-would be O(n) to determine their index in the population list (to remove them
-when they die) from their index in the 'remaining' list. Agents have this value
-stored at the beginning of the round - O(n) at the beginning of the round is
-far preferable to O(n) for every death.
-3.) The actual removal of agents from the population list must happen all at
-once in reverse numeric index order at the end of the round so that the stored
-index that agents have does not become stale.
-
-There are problems. It's not perfect, but it's relatively fast and powerful and
-quite easy to adjust or reimplement once you get your head around it. I'm very
-much open to suggestion for improvement (especially in the form of patches) and
-welcome all help, constructive criticism, derisive criticism and death threats.
-
-Things to be done:
-
-1.) Pretty graphs! Iterate () returns a collection of statistics about each of
-the classes, which can be seen used in simulate.py. There are plenty of
-plotting packages out there that can turn this information into impressive
-charts.
-2.) More built-in functionality for BaseAgent and LearningAgent. They could
-both do with a few more utility functions for competitors to use.
-3.) A more succint set of rules and documentation.
-
-Thanks for reading!
-Luke
* Or rather, it wil by the time this package is ready for distribution.
git.ucc.asn.au / progcomp10.git / commitdiff
UCC git Repository :: git.ucc.asn.au