Difference between revisions of "Darwinbots 3"

From WikiManual
Jump to: navigation, search
(→‎Adding paths)
(→‎Where's the DB3 EXE?)
 
(63 intermediate revisions by 5 users not shown)
Line 1: Line 1:
−
Darwinbots 3 is a long term project to recode Darwinbots in C# as a brand new program.  Every feature and aspect is going to be examined and refined as its added, in a framework that will ensure robustness and agility in handling bugs and new features.
+
Darwinbots 3 is a long term project to recode Darwinbots in C# as a brand new program.  Every feature and aspect is going to be examined and refined as its added, in a framework that will ensure robustness and agility in handling bugs and new features. The code can be browsed: [http://svn.darwinbots.com/Darwinbots3/ http://svn.darwinbots.com/Darwinbots3/]
  
−
== The repository ==
+
== Compiling the code ==
−
=== Introduction ===
+
=== Getting the compiler ===
−
Darwinbots3 is stored in an SVN location on Numsgil's SVN account with [http://www.hosted-projects.com www.hosted-projects.com] (which I highly recommend.  Excellent customer service).  You can browse it in an explorer, but to download it to work on, you'll need an SVN manager.  Numsgil uses [http://www.syntevo.com/smartsvn/index.html SmartSVN], which again I highly recommend.
+
You'll need a version of Visual C# that's at least 2013. Newer versions should work fine, but I haven't tested it. (Also, this all might run under Mono in Linux, but I don't have either so no promises).  You can download [http://msdn2.microsoft.com/en-us/express/aa975050.aspx C# express] for free.  The whole process will probably take several hours to do.
  
−
For those unfamiliar with version control, it's basically a way to ensure that multiple people can work on the same source code. You "check out" a copy of the current source code from the repository and store it locally on your computer.  You then change the source code in places and "commit" it back to the repository.  If there have been changes in the mean time that conflict with your changes (should be a pretty rare occurrence), SVN will notify you and ask you to resolve te problem before the commit is applied to the central code repository. Another advantage of working this way is that the entire evolution of the code is tracked. If some bug is found that was introduced months ago, you can browse through the repository at different versions of the program to find what changes caused it.
+
You will also need to install Python, at least version 3.6.  You can [https://www.python.org/downloads/windows/ download Python here].
  
−
=== Etiquette ===
+
=== Downloading the dependencies ===
−
* Prefer to post lots of small, atomic changes over large, far-reaching changes.  It's easier to integrate for other people, and minimizes the possibility of commit conflicts.
+
To compile/run the project, you need:
  
−
* Keep the repository's code running.  Don't commit a change that would break the program, or worse, prevent it from compiling. If you do anyway, fix the problem immediately.
+
* DirectX installed.  Needs to be the latest version installed.  Try running the [http://www.microsoft.com/en-us/download/confirmation.aspx?id=35 web installer] to see if you have the latest version.
  
−
=== Accessing the repository ===
+
=== Get either Subversion or a Subversion client ===
−
[https://svn2.hosted-projects.com/Numsgil/DarwinbotsCS/ https://svn2.hosted-projects.com/Numsgil/DarwinbotsCS/] This is the link for the repository.  It has anonymous access, so anyone can download and browse it.  To commit changes, you need a username and password.  Post a request for one [http://www.darwinbots.com/Forum/index.php?s=2c5129f4c423731b6c1effece256aaef&showforum=62 here].  If you haven't registered in the forum yet, please do so.  It's important that progress is talked about so others can see what's going on.
+
For those unfamiliar with version control, it's basically a way to ensure that multiple people can work on the same source code. You "check out" a copy of the current source code from the repository and store it locally on your computer.  You then change the source code in places and "commit" it back to the repository.  If there have been changes in the mean time that conflict with your changes (should be a pretty rare occurrence), SVN will notify you and ask you to resolve the problem before the commit is applied to the central code repository.  Another advantage of working this way is that the entire evolution of the code is tracked.  If some bug is found that was introduced months ago, you can browse through the repository at different versions of the program to find what changes caused it.
  
−
== Compiling the code ==
+
You can either try one of the [http://www.sliksvn.com/en/download Subversion commandline builds] if you're into that sort of thing, or try one of the GUI based Subversion clients.  I like [http://www.syntevo.com/smartsvn/index.html SmartSVN] myself.
−
=== Getting the compiler ===
 
−
You'll need a version of Microsoft Studio 2005 C# (this all might run under Mono in Linux, but I don't have either so no promises).  You can download C# express [http://msdn2.microsoft.com/en-us/express/aa975050.aspx here] for free. Follow '''every instruction''' on the page.  This will probably take several hours to do.  The good news is that even if you never start programming Darwinbots, you just found a free high quality compiler :D
 
  
−
=== Downloading the dependancies ===
+
=== Accessing the repository and committing ===
−
So far, the following are the list of program dependancies for Darwinbots3:
+
[http://svn.darwinbots.com/Darwinbots3/ http://svn.darwinbots.com/Darwinbots3/] This is the link for the repository.  It has anonymous access, so anyone can download and browse it.  To commit changes, you need a username and password. Post a request for one [http://forum.darwinbots.com/index.php/board,62.0.html here].  If you haven't registered in the forum yet, please do so.  It's important that progress is talked about so others can see what's going on.
−
* .Net 2.0 (this comes with the C# express install)
 
−
* [http://www.nunit.org/ NUnit] unit testing framework.
 
−
* [http://taoframework.com/ Tao] bindings for OpenGL and other things
 
  
−
The following are not required yet, but probably will be soon:
+
=== How you should set up your SVN projects and local directories ===
−
* Some 3D math package.  Currently leaning towards [http://www.codeplex.com/Sharp3D Sharp3D].
+
You can dump the source whereever you want.  Everything is set up with relative paths.  I usually put it on the root level myself:
  
−
I might end up creating an "install" for DB3 that includes all these dependancies, and have people add a source directory to the install.
+
C:\
 +
* \Darwinbots3Source <-- sync this to the trunk directory in the repository, or one of the tags or branches if you're working from them
  
−
=== Adding paths ===
+
=== Visual Studio solution files ===
−
In order for the UnitTest project(s) to correctly run after they're built, you need to add your NUnit bin directory to the environment paths for your computer.  For Windows XP, hit the windows key button + page break to open up a hardware dialog.  Go to the advanced tab, and hit the environment variables button.  In either the user or system box, find the PATH entry, and click on it.  Then hit the "edit" button and the following text to the end of the PATH variable value field:
+
Instead of one large master solution file to build the entire project, each module maintains its own solution file for just that solution.  Usually it will contain the module itself, some unit tests, and a test app.  This is to make checking unit tests for errors simpler, among other purposes.  All the modules spit out binaries in to the bin/Release directory, and these are checked in, so there's no need to rebuild everything very often (assuming source and binary and kept in sync, which will usually be true).  To build the entire project, you'll need to run one of the build scripts in the Scripts directory. 
  
−
*Variable Value: ;C:\Program Files\NUnit 2.4.7\bin
+
Rebuilding everything locally can help with debugging across module boundaries, though.
  
−
replace the above directory with whatever other folder you installed NUnit to.
+
=== Junk directories and bin folders ===
 +
The projects are set up to place bulky build files in the Junk directory.  This directory should always be empty on the repository, except for the "About This Folder.txt" file.  Final EXEs are built to the Bin folder.  None of the binaries are checked in to the repository.  The binaries in the Bin folder are what projects use when they want to import another (for instance, the release build of UnitTestSharp is used for the unit testing projects).
  
−
Visual Studio will now run the unit tests as a post build event whenever it builds any Unit Test projects.  This way, the unit testing is encorporated into your build process, and you're far less likely to botch something without knowing it.
+
=== You have the code, now what? ===
 +
You'll need to build all the different modules.  There isn't a single solution file to build everything (on purpose, since lots of smaller solution files are more manageable), but in the Scripts folder there's a batch file called build.py that will build everything in the correct order.  Run that file.  If you have a different version of Visual Studio than 2013 you'll need to run it from the command line with the --version flag set.  eg: For Visual Studio 2017 the version is 15 (confusingly), so you'd set --version=15 and it should work.
  
−
You will need to restart Visual Studio after doing this for the post build event to correctly find the path you just added.
+
=== Where's the DB3 EXE? ===
 +
Under Modules\Darwinbots3 there is a Darwinbots3 solution.  At the moment the Darwinbots3 binary is pretty empty, but there is a Bot.Testbed application that is starting to come together.
  
 
== Coding standards ==
 
== Coding standards ==
−
One of the nice things about C# is that it intelligently keeps everyone using the same coding style, so I won't belabor this point.  I will, however, talk about some important ideas not everyone may be aware of.
 
  
−
=== Unit testing ===
+
=== Basic Standards ===
−
Unit testing is a way to ensure that a function or section of code works like you think it should.  It is ''immeasurably'' important for keeping the code robust and bug free.  It also makes refactoring much easier.  [http://www.gamesfromwithin.com/articles/0502/000073.html this site] is an excellent introduction to Unit Testing for games.
+
Look at the code, and follow by example.
  
−
Ideally, you would write the tests first and then "fix" the program to pass those tests.  This requires some disciple that I personally don't always have, so I'm not going to ''strongly'' enforce this.  Aim for this standard anyway.  Definitely unit test as many aspects of the code you're working on as possible, even if it's after the fact.
+
=== Repository etiquette ===
 +
* Prefer to post lots of small, atomic changes over large, far-reaching changes.  It's easier to integrate for other people, and minimizes the possibility of commit conflicts.
  
−
=== Design patterns ===
+
* Keep the repository's code running.  Don't commit a change that would break the program, or worse, prevent it from compiling.  If you do anyway, fix the problem immediately.
−
I'm not too concerned about strictly following design patterns, but you should at the least be aware of them.  [http://www.dofactory.com/Patterns/Patterns.aspx This article] shows the more common design patterns and examples for them.  Personally I've found various factory patterns useful for things like the DNA language parsing and unparsing.
 
  
−
== Architecture ==
+
* Be careful what files you submit.  If it's a large temporary file you accidentally submitted it will take up repository space for ever and ever, even if you remove it from the repository later.
−
I'm designing the program around the idea of "data-centered".  You can read a paper about it [http://members.cox.net/jplummer/Writings/Thesis_with_Appendix.pdf here] (just browse through it, it's pretty big.  Focus on the part near the beginning where he explores different architecture models).
 
  
−
Basically, each module interacts only indirectly with other modules through a central data repository.  Instead of a something like monster[456].Draw(), you'd have Draw(Monster[456]).  The benefit of a design like this is that it allows you to swap different modules (change your graphics from OpenGL to Ogre, for instance) easily, lowers the allowed interdependency between modules, and lets the modules themselves be reused in different projects.
+
=== Unit testing ===
−
 
+
Unit testing is a way to ensure that a function or section of code works like you think it should.  It is ''immeasurably'' important for keeping the code robust and bug free.  It also makes refactoring much easier.  [http://www.gamesfromwithin.com/articles/0502/000073.html this site] is an excellent introduction to Unit Testing for games.
−
In general, all the game data, such a bots, shots, ties, etc., go into a central repository.  A method goes into class of a data object only if it's strictly involved with manipulating the data and not doing something to it.  For instance, a function that takes an amount a bot is supposed to be charged in nrg and gives it waste too should go with the bot's class. A function that handles collisions between bots and shots should probably go in a module. It's not strictly black and white, but generally ask yourself if adding a function ties the data directly together with a module. If we wanted to swap out one of the modules, would we find it difficult to disentangle the data repository from it?  If so, it belongs in a module (in the case of the bot shot collision, it would probably belong in the game logic module).
 
  
−
The following is a rough draft of the different modules I'm planning:
+
Ideally, you would write the tests first and then "fix" the program to pass those tests.  This requires some discipline that I personally don't always have, so I'm not going to ''strongly'' enforce this.  Aim for this standard anyway.  Definitely unit test as many aspects of the code you're working on as possible, even if it's after the fact.
  
−
* DNAModule AKA Sunweaver - A fairly self contained module that handles most of its own functions, parsing, etc.  Very little interfacing is needed with it beyond a few "black box" controls.
+
If you want to submit code without tests, it'll probably end up in the trashcan, honestly, when time comes for me to figure out how it's supposed to work (and why it's currently not working).
−
* Graphics Module - Consists strictly of calls to OpenGL, assuming I use OpenGL.
 
−
* GUI Module - Contains the dialog boxes and windows the user will probably use and see, all written with Forms.
 
−
* Game Logic Module - Handles the core simulation, minus physics and DNA.
 
−
* Physics Module AKA Lodestone Physics Engine - The physics engine for Darwinbots, coded for a great deal of feedback as far as collision forces, etc.
 
−
* Networking - Handles interfacing with the internet.  Users could download bots from an online database right from the program, for instance.  Also internet sharing, program updates, etc.
 
−
* Disk IO - Handles serializing the data.  Data will probably be saved as zipped XML files, to allow for outside manipulation through scripting languages.
 
−
* MainExe - Basically nothing more than calls to the different modules to initialize them and start the game loop, calling each module in the proper order.
 
−
* Central Data Repository - Stores references to bots, shots, ties, DNA, etc.  Very little algorithmic work going on.
 
  
−
These modules ideally would end up as seperate DLLs to help enforce modularity, but this might cause cyclic dependancies, so I'm not holding my breath.
+
== Release pattern ==
 +
When a new release is ready, it's given a version number.  The format is:
 +
* '''Darwinbots3 AXXXXX.exe''' - An alpha release.  The XXXXX is the source control revision (ie: the changelist number in the SVN) corresponding to the executable
 +
* '''Darwinbots3 BXXXXX.exe''' - A beta release.  The XXXXX is the source control revision corresponding to the executable
 +
* '''Darwinbots3.0.exe''' - The first feature complete and stable release.
 +
* '''Darwinbots3.XXX RC1''' - A release candidate.  The number after RC is the release candidate version.  The XXX is the version number (starts at 001, goes to 999).
 +
* '''Darwinbots3.XXX''' - The stable release for version XXX.
  
−
== Design ==
+
Note that these files alphabetically sort according to when they are expected to release.  This is important.
−
Visit the [[Darwinbots 3 wish list | wish list]] to see the major features under consideration from the point of view of the end result.  Discuss them [http://www.darwinbots.com/Forum/index.php?showforum=62 in the forum].
 

Latest revision as of 05:06, 6 May 2017

Darwinbots 3 is a long term project to recode Darwinbots in C# as a brand new program. Every feature and aspect is going to be examined and refined as its added, in a framework that will ensure robustness and agility in handling bugs and new features. The code can be browsed: http://svn.darwinbots.com/Darwinbots3/

Compiling the code

Getting the compiler

You'll need a version of Visual C# that's at least 2013. Newer versions should work fine, but I haven't tested it. (Also, this all might run under Mono in Linux, but I don't have either so no promises). You can download C# express for free. The whole process will probably take several hours to do.

You will also need to install Python, at least version 3.6. You can download Python here.

Downloading the dependencies

To compile/run the project, you need:

  • DirectX installed. Needs to be the latest version installed. Try running the web installer to see if you have the latest version.

Get either Subversion or a Subversion client

For those unfamiliar with version control, it's basically a way to ensure that multiple people can work on the same source code. You "check out" a copy of the current source code from the repository and store it locally on your computer. You then change the source code in places and "commit" it back to the repository. If there have been changes in the mean time that conflict with your changes (should be a pretty rare occurrence), SVN will notify you and ask you to resolve the problem before the commit is applied to the central code repository. Another advantage of working this way is that the entire evolution of the code is tracked. If some bug is found that was introduced months ago, you can browse through the repository at different versions of the program to find what changes caused it.

You can either try one of the Subversion commandline builds if you're into that sort of thing, or try one of the GUI based Subversion clients. I like SmartSVN myself.

Accessing the repository and committing

http://svn.darwinbots.com/Darwinbots3/ This is the link for the repository. It has anonymous access, so anyone can download and browse it. To commit changes, you need a username and password. Post a request for one here. If you haven't registered in the forum yet, please do so. It's important that progress is talked about so others can see what's going on.

How you should set up your SVN projects and local directories

You can dump the source whereever you want. Everything is set up with relative paths. I usually put it on the root level myself:

C:\

  • \Darwinbots3Source <-- sync this to the trunk directory in the repository, or one of the tags or branches if you're working from them

Visual Studio solution files

Instead of one large master solution file to build the entire project, each module maintains its own solution file for just that solution. Usually it will contain the module itself, some unit tests, and a test app. This is to make checking unit tests for errors simpler, among other purposes. All the modules spit out binaries in to the bin/Release directory, and these are checked in, so there's no need to rebuild everything very often (assuming source and binary and kept in sync, which will usually be true). To build the entire project, you'll need to run one of the build scripts in the Scripts directory.

Rebuilding everything locally can help with debugging across module boundaries, though.

Junk directories and bin folders

The projects are set up to place bulky build files in the Junk directory. This directory should always be empty on the repository, except for the "About This Folder.txt" file. Final EXEs are built to the Bin folder. None of the binaries are checked in to the repository. The binaries in the Bin folder are what projects use when they want to import another (for instance, the release build of UnitTestSharp is used for the unit testing projects).

You have the code, now what?

You'll need to build all the different modules. There isn't a single solution file to build everything (on purpose, since lots of smaller solution files are more manageable), but in the Scripts folder there's a batch file called build.py that will build everything in the correct order. Run that file. If you have a different version of Visual Studio than 2013 you'll need to run it from the command line with the --version flag set. eg: For Visual Studio 2017 the version is 15 (confusingly), so you'd set --version=15 and it should work.

Where's the DB3 EXE?

Under Modules\Darwinbots3 there is a Darwinbots3 solution. At the moment the Darwinbots3 binary is pretty empty, but there is a Bot.Testbed application that is starting to come together.

Coding standards

Basic Standards

Look at the code, and follow by example.

Repository etiquette

  • Prefer to post lots of small, atomic changes over large, far-reaching changes. It's easier to integrate for other people, and minimizes the possibility of commit conflicts.
  • Keep the repository's code running. Don't commit a change that would break the program, or worse, prevent it from compiling. If you do anyway, fix the problem immediately.
  • Be careful what files you submit. If it's a large temporary file you accidentally submitted it will take up repository space for ever and ever, even if you remove it from the repository later.

Unit testing

Unit testing is a way to ensure that a function or section of code works like you think it should. It is immeasurably important for keeping the code robust and bug free. It also makes refactoring much easier. this site is an excellent introduction to Unit Testing for games.

Ideally, you would write the tests first and then "fix" the program to pass those tests. This requires some discipline that I personally don't always have, so I'm not going to strongly enforce this. Aim for this standard anyway. Definitely unit test as many aspects of the code you're working on as possible, even if it's after the fact.

If you want to submit code without tests, it'll probably end up in the trashcan, honestly, when time comes for me to figure out how it's supposed to work (and why it's currently not working).

Release pattern

When a new release is ready, it's given a version number. The format is:

  • Darwinbots3 AXXXXX.exe - An alpha release. The XXXXX is the source control revision (ie: the changelist number in the SVN) corresponding to the executable
  • Darwinbots3 BXXXXX.exe - A beta release. The XXXXX is the source control revision corresponding to the executable
  • Darwinbots3.0.exe - The first feature complete and stable release.
  • Darwinbots3.XXX RC1 - A release candidate. The number after RC is the release candidate version. The XXX is the version number (starts at 001, goes to 999).
  • Darwinbots3.XXX - The stable release for version XXX.

Note that these files alphabetically sort according to when they are expected to release. This is important.

Retrieved from "http://wiki.darwinbots.com/index.php?title=Darwinbots_3&oldid=5795"