Now that I'm not the only one working on development, it's time for a "setup guide". This will be in several sections for navigation, so you'll have to forgive me the posting spree that's about to follow.

1. Vision
   
2. Getting your IDE
   
3. Getting the sources
   
4. Getting the dependencies
   
5. Setting up your workspace
   
6. Finding your way around the source tree
   

Imagine being able to build any Lego creation you can imagine without running out of pieces. Imagine being able to build a mech, or a spaceship, or a tank, and immediately jumping into the pilot's seat for a fight to the death. Imagine building secret bases under the kitchen stove, and towns in the cupboards, and then leveling them, or dashing through the streets of a medieval village playing capture the flag.

Anyone should be able to build a world, and anyone should be able to build a game in that world. We want to support both of those things.

Core principles: Fun, Free, Extensible.

To get a sense of what we're aiming for, try downloading the old TGE 1.5.2 based release. Vehicles and weapons and players still need to be modeled externally, and we don't have LDraw support yet, but the awesome building and modding mechanics are there. Here are also some inspiring screenshots of days gone by, to inspire us to strive for new heights of greatness:


screencapturecontest by elfprince13, on Flickr


Untitled by elfprince13, on Flickr


pic_00044 by elfprince13, on Flickr


observation deck by elfprince13, on Flickr


pic_00016 by elfprince13, on Flickr


pic_00013 by elfprince13, on Flickr


pic_00012 by elfprince13, on Flickr

pic_00017
by elfprince13, on Flickr


Back to top.

I'm going to assume use of Eclipse, because (unfortunately) it's the best IDE for JVM languages.

1. Get the 4.0.x branch of the Scala IDE (for Scala 2.11), this is prepackaged with Eclipse
   
2. Run it at least once to setup a workspace folder.
   

Back to top.

There are several relevant GitHub repos for the main project. You'll need a Git client. On OS X, I'm generally happy with the official GUI client for basic needs, but not sure how it is on other platforms. The command line version isn't that hard to figure out, and Google can provide some good explanations of how it works. You'll need to check them out as follows (and it will probably be beneficial to fork copies of the ones you'll be working on into your personal GitHub account), but don't do it quite yet!

1. FreeBuild contains the main engine sources, and the scripts.
   
2. LDrawParser contains the grammars for the LDraw parser, which will eventually feed all of our 3d models.
   
3. GLSL-Shader-Editor contains the source and grammar for the GLSL shader editor that will be integrated into the engine.
   
4. libcrane is a native library to find the OS-appropriate folders for storing various sorts of runtime data.
   

What you will want to check out first are the Helper Scripts. Clone this repository into your Eclipse workspace folder, and proceed to the next section.

Back to top.

1. Open up `autosetup.py` from the Helper Scripts folder, and edit the variables at the top to match your machine settings. You'll also need to change the repository URLs if you chose to fork any of the repos above. Unless you've already setup Eclipse for FreeBuild in the past, make sure that both `SKIP_PLUGINS` and `SKIP_SHARED` and set to `False`.
   
2. Run `autosetup.py`. If you did everything right so far, it'll run to completion, if you hit errors along the way, adjust the configuration variables to match your machine. Once the Eclipse plugins have been installed successfully, you will save a lot of time by setting `SKIP_PLUGIN=True` for further runs of the script.
   
3. If you have trouble building libcrane automatically, you might need to stage a hand intervention at this point. On a Unix-y system, you probably just need to run make. On a Windows machine, you should be able to use the included VS project. `testcrane.cpp` probably won't build on OS X. Don't worry about it. You just need the dynamic library.
   
4. You should now have a number of repositories downloaded into your workspace directory.
   
5. Additionally, FreeBuild-HelperScripts/shared-libs will be populated with jars of common dependencies. A number of these libraries come with src distributions as well as the jar file. If you end up needing to debug something within them, you'll want to have it handy. If it seems unlikely that you'll be working on that part of the engine, probably no need to keep it around.
   

Back to top.

1. Open the Eclipse that has Scala IDE/PyDev/AntlrIDE.
   
2. File -> Import -> General -> Existing Projects into Workspace
   
3. Browse to select the workspce directory. Make sure "Search for nested projects is checked", and "Copy projects into workspace" is unchecked. Select all of the listed projects: CSSBox, FreeBuild, FreeBuild-HelperScripts GLSL-Shader-Editor, jStyleParser, LDrawParser, and libcrane. Press Finish.
   
4. Open the Eclipse preferences, go to PyDev, then Interpreters, then click Jython Interpreter.
   
5. Click "New", enter "Jython 2.7 beta" as the interpreter name, and browse to select the standalone jar in `shared-libs`.
   
6. It will complain that it couldn't find the Python stdlib. Press "Proceed anyways", then select the new interpreter from the list, and switch to the Libraries tab below. Press "New Jar/Zips", and select the standalone jar again. Press Open, Apply, and Ok.
   
7. If you get compile-time errors at this stage (before having changed any code yourself), you may wish to refresh each project by right clicking and selecting refresh. If you still get them, come ask here for help.
   
8. To run, you should be able to right-click on `net.cemetech.sfgp.freebuild.Main.scala`, and Run or Debug as a Scala application. If you get run-time errors, that's okay, we're still working =) You can also add additional Run + Debug configurations at your leisure, using the Run menu.
   
9. Browse through `Main.scala` to understand how the application is launched and what options are available (for example, how to change the main script file at runtime). Browse through libcrane and `net.cemetech.sfgp.freebuild.platform.ConventionMinder.scala` to figure out where log files are being stored.
   

Back to top.

Within the primary FreeBuildJ directory there are three hierarchies of folders that are important to understand as a developer.

net.cemetech.sfgp.freebuild
This is the package containing the main engine code. It is divided into several classes and subpackages

• `Main.scala` -> this file is in charge of constructing a Jython interpreter and the logging service, and choosing a main script to run, which will return an `AbstractDriver` subclass, whose `mainloop` will be executed.
  
• `boxui` -> contains for code for a user-interface layer built on CSSBox (and implementation of an OpenGL-driven renderer for HTML/CSS UI elements)
  
• `console` -> contains an implementation of the multiplexed logging service and a class representing the Jython interpreter. You shouldn't have to pay it much mind, unless you want to subscribe a new `OutputStream` listening to standard out/standard err (e.g. for a GUI based console).
  
• `drivers` -> this contains implementations of "main loops" that the engine might want to run. Since the world-representation should be separate from rendering (to cleanly separate dedicated servers from clients, or whatever odd utilities someone might want to construct), we all subclass `AbstractDriver` here. It will probably be useful to added a `DedicatedDriver` sometime soon, for net + physics debugging. Any new drivers will need to be registered, probably by adding a line to `Main.scala` (where `GFXDriver` is currently registered), unless we come up with something cleaner. `GFXDriver` currently consists of a UI rendering loop.
  
• `gfx` -> this contains everything related to rendering. It's under active development and things might change. But look here if you need to see how rendering stuff works.
  
• `platform` -> any platform-specific code related to the engine should go here. As of now, this is only `ConventionMinder`, which is the binding to libcrane, for finding things like user data directories.
  

Eventually we'll need to add other subpackages for at least net-code and physics, as well as classes representing the non-physics related abstractions of in-game objects, and stuff like that.

main.py + scripts

• `main.py` -> implements a bunch of utility functions, and also initiates the reading of certain preferences (for now), and reads command line arguments
  
• `scripts` -> contains a class implementing a `DOMSource` on top of the Validator.nu parser, to work around CSSBox defaulting to NekoHTML. This probably doesn't need to be a top level script, but we haven't organized everything else yet. Also contains an `__init__.py` that should probably be a template for most subpackages, as it handles things in a nice dynamic fashion.
  
• `scripts.gfx` -> contains the code used for our configurable graphics pipeline (still in the works)
  
• `scripts.ui` -> contains the code that sets up all of the UI handles used by `GFXDriver`, plus a module defining a representation for key bindings that trigger actions, and another module that sets up our dummy main menu. Any scripts related to user interaction should go here (though possibly eventually with better organization).
  
• `scripts.util` -> contains currently only a topological sort algorithm to be used for dependency analysis, among other things. Can be populated with other utilities that don't appear to belong elsewhere.
  
• `scripts.prefs` -> the `__init__.py` for `scripts.prefs` subpackages are a little bit more elaborate. They define symbols that should be exported by that subpackage, and read a global configuration dictionary to decide which module in that package should be chosen to export them from. Right now we only have keybindings (which is more or less a dummy/holdover, from brief flirtation with librocket), and fonts, which just provides a handle to a directory full of fonts that we want to use. The full preferences system isn't set up yet, but between `main.py` and this you should have a good flavor for how it will work.
  

Eventually, we'll need to add server + client subpackages, plus probably a "common".

data
Sounds, models, textures, and ui related stuff will go in here. Add directories as needed, in an organized + hierarchical fashion. As with scripts, the top of these hierarchies should probably be related to server/client dichotomies, plus some stuff in common.

Back to top.

Sadly the skill needed to work on this awesome project is over my head but I cant wait to see where it goes was always fun goofing off in the KermCave last time I played


Though is it written in python/java? Cause I like python

It's a learning project! Hop in and figure stuff out =)


Ooh, did you play with a group? I haven't seen any servers pop up in SAX for a while.



Jython (i.e. Python for JVM), plus Scala mostly. Java can fit in just fine, but I tend to avoid it where I can use Scala instead.

I just might I will have to attempt to get an IDE setup and then nag you on irc

Also this was probably 2 years ago :X that I last played it has been a while..I kept not understanding the jetpack and dieing

Cool, lemme know if you do so.

Also, bump to say that instructions have been updated somewhat over the course of today. Changes have been in particular to the handling of CSSBoxLib, and to how glg2d is added to the build path.

This was back while I had my linux dedi still up and running, which as soon as you tell me its playable will be up again on a much improved box.



Python and Jython I can handle and while I've had some official Java courses it was never a fluid to write for me as C#, Python or C so I'm glad we're sticking there.

Also not to take things too off topic but was there ever a post explain the reason for running in the JVM and thus using Scala/Jython rather than C the CLR and using IronPython/F#/C#? Also I'll have to see if I can get this setup to dev with VIM+tools on the server since there is little chance I'll be firing up full blown Eclipse on there unless I want to fight X forwarding again.

• Every time I've checked, JVM has way more mature + predictable garbage collection. .Net is catching up, but Mono is still utter crap on this front.
  
• Secondarily, I have no interest in subjecting myself to Mono or supporting Microsoft's closed-off ecosystem. Java is meaningfully open source and not at risk of disappearing if a single company decides to abandon it (OpenJDK has been the reference implementation of the standard libraries for almost a decade now, supported by Apple/IBM/Oracle/Red Hat/SAP, and all of the relevant VM implementations are also open source).
  

SBT (Scala Build Tool) should get you through pretty much all of it by hand, as long as you're comfortable putting together a classpath. Maybe also some ANT for compiling the various grammars.

I don't want to start a CLR vs JVM thread here and my preference mostly comes from C# syntax and conventions and design just being that nicer than Java's in my opinion. Since your code is more Scala and Jython that's less of an issue though java design did effect design choices in the JVM which will show.

With how much adjusting Garbage Collecting settings can darastically change Minecraft and other Java game performance I'd say Java's is far from predictable.

Also in both cases I don't think the Garbage collector would be much of a direct impact to us unless we start abusing objects to the extreme and even then CLR languages have had better ability to interact with the GC since day 1 and Java ended up copying features from C# there.



I'll accept this though with how many other major games are built on C#+XNA/MonoGame/FNA or C#+SDL# I would say we are just fine not to mention MS isn't going anywhere any time soon.

Heck there are tons of Unity based multiplatform games which while using a C++ core the scripting is done in C# using Mono, they don't even bother with MS's .Net implementation.


Depending on how sane or not the class path stuff I'll have to give that a look, and just a jab here mono includes a tool to easily build csproj and the like with a simple command no class paths setup needed. Most of what I'll be messing with will be scripting anyway so as long as I don't need to do major recompiles to change scripting I should be good. And if the changes I'd be making do require a full recompile then I'd say something is wrong and a relook at how the scripting or plugin system works needs to be done.

Either way if I get something up and running I'll post here with details of what I've done to get things setup.

C# compiler is completely open sourced.

Compiler ≠ ecosystem. The reference (and most-widely-deployed) implementations of the Java compiler, virtual machine, and entire J2SE class library are open source.


In HotSpot, Concurrent mark-and-sweep and G1 both only stop-the-world as a last resort. That's a huge plus for reducing jitter. Both of the options available to Mono stop the world for every collection (and Boehm, which was the default through last year, is simply awful).

Predictable doesn't mean "magic", predictable means "not jittery".


The key difference being that the core was in C++, which is not memory-managed.


And that's enough off-topic discussion for now.


Ant, Maven, and I think SBT all offer "magic" project management, but you'll need to make a project yourself. You should be able to figure it out by cat'ing Eclipse project settings. The slightly tricky thing is to make sure you exclude any system-provided JNA dynamic libraries, because they're typically out of date and will supercede the version on the classpath. If you have problems, use -Djna.nosys=true at runtime.

I think we've probably hijacked this thread enough with language/tech discussion. I will say, though:

Hehe, jittery. JITter. Get it? 'Cause it's JIT compiled? Hehehehehe.

Okay, so unrelated to language-war issues, I got curious about looking at the UI layer again, since the currently planned system feels a bit clunky and discovered that my best option is probably ditching the Graphics2D based approach altogether and just writing my own subclass of CSSBox's BoxRenderer class. There's already an official subclass that renders to SVG instead of a Graphics2D context, so I should be able to work from that pretty closely to get a sense of how to easily turn bypass the Java graphics layer and output some vector graphics directly.

(this is temporarily out of date as I've been working on an auto-setup script that handles most of it. it's pretty close to ready for prime-time, so hopefully I'll be able to update the instructions soon)

All up-to-date! Hope the easy-peasy installation process will inspire some of you to help