The Way Things Are

A bit of background on roughly how things are implemented at the moment.  Aui is the custom UI system that all the screens and other interactive bits are built using.  This has a bunch of generic widgets, like buttons, labels, scroll bars, etc.  Within the Tako package, I have all the Tako custom widgets (for things like the agent icon buttons and the codex mantle list), as well as all the screens and popups, which themselves are just widgets.

The component which glues all of this together is the ScreenController.  ScreenController does a bunch of unique stuff.  It is the root widget in the widget family tree.  The Tako game class (Slick-derived) calls ScreenController’s update(), render() and resize() methods directly.  ScreenController also does a bunch of currently-pretty-nasty event handling such that any screen call do something like triggerEvent(widget, “screen MainMenu”) to open the main menu, or triggerEvent(widget, “popup mantleInfo <mantle Id>”).  It’s a little bit gross, but it’s functional.

ScreenController allows a single screen to be visible, but maintains a popup stack.  This means that while you’re in the Codex, for example, you can keep clicking on links that pop up more mantle info popups and it keeps something of a history as you keep hitting back.  This will require a bit of reworking in the long run, because you can theoretically get into a situation where you’re running out of memory due to so many popups being in the stack.

The actual game logic is contained in a separate widget-derived component that exists outside of this system, Campaign.  This Campaign widget is always rendered underneath the currently active screen and popup, and drives the game logic for things like the avatar traveling and triggering encounters, and also responds to events requesting mantle/party changes.

The Conundrum

This is all well and good, and everything is working quite well at the moment.  However, it does pose a bit of a strange issue now that I’m starting to look at battles.  See, the Campaign widget functions like the back-end for gameplay, and there’s another widget that functions as the front-end: the CampaignScreen widget.  All of the user interaction happens within CampaignScreen.  There are widgets in Campaign that are used for rendering encounters and parties and stuff, and their tooltip displaying is actually handled by CampaignScreen, but nothing on the world map is actually interactive.

So I’m stuck in a position where I still want to continue keeping the front-end/back-end separation in place — it actually looks great having the game render in behind the menus without the clutter of the game UI after all — but if the Battle component is going to be maintaining the queue of agent events, and BattleScreen is maintaining the graphical/interactive representation of that…  Well, it just gets even uglier, I find.  I have to end up doing a bunch of agent lookups to ensure that the visual timeline aligns with the actual timeline.  Especially when you consider that some agents may from time-to-time disappear altogether from the timeline, it’s just especially ugly.  Gross!

The Solution

Okay, so it’s really not that big of a deal.  I’ll keep a queue of battle events in Battle, which will be a bunch of elements containing agent + event (command or action) + optional ability (for active wait or normal action).  Since this queue only updates infrequently, I can make use of the “refresh” functionality I have in place with Aui — essentially I can allow Battle to trigger a ‘refresh’ event which will ultimately cause the visual timeline to repopulate.  This will also allow the BattleScreen (which will be responsible for things like selecting abilities and targeting) to update based on whose action is available.

I’m not entirely sure why this was making my head spin so much, but it doesn’t matter!  I have a plan of attack, and hopefully Tako will have some playable battles before too long. 

I revamped the Codex window, and all the other list-of-mantle windows while I was at it.  I needed to do so because I wanted the following for leveling up:

Not only did I manage to get that done, but I also (perhaps inadvertently) introduced the basic metagame.  It’s currently possible to spam the skill check in first visible encounter to award a whole bunch of experience and cap out your agents, and this will actually result in the Codex opening up too.  Now, there aren’t any flashing lights or effects or anything to tell you that you’ve unlocked new mantles, but the functionality works!

So, the last remaining tasks for Tako-Gimel are:

• Validate Daleth task breakdown.  I first did the task breakdown for the next milestone (combat encounters) at the beginning of this milestone.  I think I might have to stop doing these breakdowns a milestone ahead, judging by the amount of learning and revamping I’ve been doing while working.  This means that the next task…
• He task breakdown… is no longer needed for this milestone.  That’s “He” the Phoenician letter (according to wikipedia) rather than the pronoun.
• And a few miscellaneous development tasks that are either feature-creepy or things I don’t really need.
• Tilesheet improvements.
• Seasons.
• Trading.  (This is something that I don’t really need a ‘system’ for, since I can just whip up something specific to any given encounter.)
• Agent AI.  (This will almost certainly end up becoming its own milestone later on — giving agents personalities and having them react to the things the player does.  Or, it’ll just end up getting cut!  Dunno!)

…and then it’s on to combat encounters!  Whole new feature, should be interesting.

Took a little bit of time tonight to toss in some utility methods for getting agent gender (the current plan is to have the gender tied to race, so you’d have both male and female races when appropriate), and to fix up the “Travel” button ingame.  It was a bit flaky before, and it feels a lot more solid now.

Aside from that, as shown in the screenshot above, I am beginning to work on the leveling system!  Here’s how leveling is going to roughly work…  After each encounter, all agents in your party (not in the squad) will receive X amount of experience, based roughly on the difficulty of the encounter.  Once an agent gets a total of, say, N experience, they gain an “Upgrade Point”.  The player can then spend that point to upgrade any one of that agent’s mantles (race, class or artifact) if that mantle has any upgrades available in its “upgrade path”.  Looking at the screenshot there, you can see that the Warrior class can upgrade into Warrior II, then Warrior III, and then finally into one of two completely different classes which haven’t yet been unlocked.  These would become visible once the agent reached Warrior III.

Each additional upgrade point for a specific agent will cost more than the last.  I expect that by doing this, and by having new agents ‘collected’ over the course of a campaign, it should hopefully space out gaining these upgrade points pretty evenly without being totally even.  It does create some interesting gameplay twists — like being able to level up an artifact quickly with a newly-acquired agent to then return to your avatar for whatever reason.

After a bit of discussion, I’ve decided to handle agents in pretty much the same way as artifacts.  You essentially have an ‘inventory’ of agents that you can draw from to fill up your party.  If the party is full (currently four members), you have to remove a member first.  I also spent some time reorganizing the party frame to show the agent’s icon, but I’m not sure I like it.  Well, I do like the icon being there, but now when you open the member details panel, it’s REALLY big.  I’m considering taking the details panel out, and instead using the agent info popup for agent interactions.  That’s something I’ll tackle later during revisions, though.

Next up: leveling!  Once I get the leveling system in place, it’ll be time to move onto combat encounters.  I’m stoked!

I have put in a system for campaign scenarios, including being able to finish a scenario.  In the example I have in place right now, there’s only a very rudimentary win/loss script set up, but it should be pretty easy to extent the system to allow for a whole range of greys versus black-and-white winning-or-losing.  The nice thing about how the demo scenario is set up is that the encounters in the world aren’t specifically hard-linked to the scenario.  This particular scenario has ‘fame’ as a measure of victory, and the encounters simply boost your fame.  This type of relationship will hopefully allow many encounters to ‘plug in’ to scenarios without too much effort.

I also have designed a leveling system that I’m hoping will work, but I’ll talk about that a little later when I have it in place.

I have added traits to the mantles, and added the functionality to prevent conflicting traits from being put together during avatar creation.  Still have to do the same for ingame equipping, but I’m happy to have done a bit of Tako work tonight at all!

Have finished changing things over to the slightly-refactored aui, and also added in auto-scaling functionality, so as the window resizes, the game scales up or down properly.  This means that it will no longer be possible to have a UI that overflows the window (unless your window is smaller than 320×240, of course).  You can still decide whether you prefer a larger or smaller scale, and Tako will try its best to accommodate.

There are a couple more things I want to refactor before I can really get cracking again on development, but they’re not major things.  Specifically, I want to add getLeft/Top/Right/Bottom() methods to Widget, and possibly add in some static factory/builder methods for creating widgets.  I’m not so sure about that last one, though.  Will have to give it a shot and see how the code ends up looking!

Oh, and three weeks until Dark Souls! 

There’s not really anything new to see in this build, but under the hood, the code is a lot cleaner.    Putting my Effective Java reading to work!

I am able to circumvent the ‘hacky boxes’ issue (mentioned here) by using a JFrame, which also allows me to have a nicely-resizable window.  However, I have a new issue now where the application is initially blank, until you either resize it larger or move it.  It will become blank again if you resize the window smaller.  I’ve been digging and am having a lot of trouble figuring out why this is the case.  Have yet to try it on another machine, though.  Maybe it’s just a problem with my video card or something.

I’ve also finished reading Effective Java, and will likely being doing a bit cleanup of Tako — most specifically of aui, which is supposed to be the go-to library for me for UI now and in the future.

The source for this tutorial is available at Bitbucket (https://bitbucket.org/apocriva/tutorials).  Full tutorial after the break!

Directory Structure and Source Control

For source control, I use a Mercurial (Hg) repository, typically hosted on Bitbucket, using tortoisehg.  I try to ensure that it’s possible to sync to the latest, load the project in Eclipse, and build/run right out of the box.  I still don’t know if I have things 100% correct, but I’ll make a note below of the Eclipse files which I currently store in Hg, and how the .hgignore file filter is set.  I won’t, however, belabour Hg, since this is a Slick/Eclipse tutorial, and not a Mercurial tutorial.

With that in mind, I’ll be referring to the Hg repository root as {Root}.  If that maps to something like “C:\dev\tutorials” for you, then you should read “{Root}\Eclipse” as “C:\dev\tutorials\Eclipse”.

Here’s the directory structure we’ll be setting up:

• {Root}.  Contains the .hgignore file and the .hg folder.
  • Common.  Certainly not the most space-saving way of doing things, but a way I’m used to doing it from my nine-to-five game dev job, I keep a full copy of the version of each common library I’m using on a project within that project’s directory structure.  This means that what I have in my repository won’t suffer from breakages due to new library versions if I have to build the project later.  I’m almost positive this would also be a legal problem if I had the Common folder in the repositories publicly available, but I don’t.
  • Eclipse.  Eclipse-specific metadata stuff.  I have this in its own folder so that it’s clear that the .metadata folder is an Eclipse construct, and not part of source control, or directly part of the project.
  • Project Folders.  Each project created within Eclipse goes in its own folder, with quite a few source folders.  In the base project folder, you’ll find the very-important .classpath file.  You may have to hand-edit this later to properly have relative paths.  This folder also contains any Ant build files that are used for things like building data.  The paths within the base project are split into two categories: those which contain source files, or files otherwise needed by the build, and therefore must be in the Hg repository; and those which are generated as part of the build and therefore do not reside in the repository.
    • Source Folders.
      • lib.  Contains the jars and native dlls that will later be built into a distribution.  These don’t technically have to be here, since they exist under Common, but the build scripts were a lot more straightforward to set up assuming we just had to blindly copy this folder over.
      • src.  Contains Java source code.
      • srcData.  Contains source data, including all working files (things like PSDs, XCFs, etc) and generally most exported files (PNGs, WAVs) which will be copied over directly.  Some files in srcData get processed by the build pipeline, with the resulting generated files ending up elsewhere.
    • Build Folders.
      • bin.  Contains .class files built from src.
      • data.  Contains the built and copied data from srcData.  This is the data accessed by the game when running/debugging from within Eclipse.
      • dist.  Contains a full distribution of the project.  The projects I work on in development use getdown for distribution, so this folder contains a bunch of things related to building that distribution.  Most importantly, it contains a zip file with the getdown updater and the built data to post to FTP.
    • I lied, there’s a third category: Miscellaneous Folders.  Each project generally has a few folders which are unique to that project, or some temporary build folders.  I could clean this up a lot, and I may end up doing so.

Setting up the Eclipse Workspace

I apologize in advance if there’s anything missing here for getting set up from a fresh installation of Eclipse.  I haven’t been familiar enough with the IDE to know what settings are project-specific, and which are global.  Just drop me a line if anything doesn’t jive correctly, and I’ll get the tutorial fixed up!

When booting Eclipse, it will ask you which workspace you’d like to open.  The workspace for this tutorial is going to be “tutorials”, and as mentioned above, the Eclipse workspace files go in the Eclipse subfolder of {Root}, so we tell Eclipse something like: “{Root}\tutorials\Eclipse”.

The first thing we do from an empty workspace is create a project.  Select “Java Project” from the New Project wizard, and for the project name enter something classy (for me, “Tut00″).  We also change the location of the project to be a sibling of the Eclipse folder.

You can just hit Finish from here to create the project, and if Eclipse prompts you to go to the “Java perspective”, you want to let it!  Note that it is possible, from the next step of the wizard, to set up the project dependencies for things like LWJGL and Slick, but in the event that you’ve skipped that panel, it’s just as easy to explain how to do so from the Java perspective directly.  Less straightforward is re-creating the project just to access that step of the wizard.

Once the project is created, right-click on it and add a new folder.  In the new folder wizard, click Advanced, select Linked Folder, click Variables, and add a new variable called COMMON_LOC, which points to ${WORKSPACE_LOC}\..\Common.  Then use this as the location for the folder.

Now go to the project Properties window (by right-clicking on the project).  Go into the Java Build Path tab.  Select “Add JARs…” and find slick.jar in the Common folder we just added.  Once this is added, expand the tree view beside the jar, and set its source, javadoc, and native library locations.  Repeat for lwjgl.jar (and note that the Slick distribution at the time of this writing doesn’t have the proper 64-bit native libraries for lwjgl, so you’ll have to get those separately).  Things should end up looking something like this:

At this point, you’re able to build and run a simple Slick application!  Feel free to try adding TutGame.java to test it out.

Data Build Pipeline

It was important for me to get a functional data build pipeline in place, since that’s what I’m used to from the day job!  I use Ant for this.  The first thing to do is create an Ant project file, which is simply an XML file, in this case called “build.xml”.

I’m not going to cover anything about Ant here, but here’s a very simple build.xml.  This will simply copy all png files from scrData to data.  From the dropdown beside the run arrows, go to “External Tools Configurations”.

From within that configuration dialog, double-click Ant Build.  It should automatically reference build.xml.  You can rename the run configuration whatever you like, as long as it still points at build.xml.  Under the Refresh tab, I always have “Refresh resources upon completion.” -> “The entire workspace” checked, so that all the built files show up properly in the workspace view.  In the Common tab, you can check “External Tools” under “Display in favorites menu” to have the build available all the time easily from the run dropdown as shown in the figure above.

The build script will fail if you don’t have a srcData folder, but that’s okay!

Ant is easily extensible if you need to add custom tasks.  The easiest thing to do in my experience has been to add a new project to the workspace, have the build task source code there, and have that project export its .jar back into the main project when it builds via an Ant build step.  There’s probably a more concise way of doing this, though.

What to Source Control?

I’ll be honest, I’m not 100% sure about this section.  There are a lot of Eclipse files that definitely need to stay out of source control.

First and foremost, let’s set up the ignore filter.  Again, as noted above, I’m expecting you to be using tortoisehg.  Right-click anywhere in Explorer under {Root}, and in the TortoiseHg submenu, select “Edit Ignore Filter”.  Here’s an example of what my ignore filter looks like:

The only Eclipse-related files that show up here are the project ones (for Tut00).  In order for the launch settings to be saved in Hg, we have to manually add the files in Eclipse/.metadata/.plugins/org.eclipse.debug.core/.launches.  From what I can tell, Eclipse has some hardcoded paths in there, though, so I don’t know if it’s possible to have a workspace checked into Hg that will work right out of the box.  One thing that we can do is modify our projects’ .classpath files manually to change the absolute paths to relative paths.

Further Pipeline Setup

Beyond the basic data build, I typically have a “distribution” pipeline, which includes packaging data and code together, and posting the result in an accessible place.  That’s a topic for a future tutorial, however!