MARS MIPS Simulator Lockup Hackfix

If you are attempting to use Missouri State University’s rather excellent MIPS Simulator and IDE, MARS, to develop an application which uses the bundled Keyboard and Display Simulator (though it seems  unlikely that you would be doing so seriously today), you may encounter a sporadic bug where the entire MARS application will lock-up, and you have to end-task it.

I personally encountered this while attempting to make a simple Snake clone just over a year ago, during the Console Development 1 module of my (WIP) BScH Computer Games Programming degree and the University of Derby. At that time me and a friend tore open the MARS .jar in order to probe for the cause of this, and were actually able to implement a little work around. Since posting about this project here and putting a video demonstration up on YouTube, I have been asked several times about how we were able to do this, and rather than repeatedly send out links to the email I originally sent to Ken Vollmar, I thought it might be nice to have a decent guide I can direct people to.

Note that the below instructions cover a quick ‘n’ dirty fix, which may introduce other errors (though I haven’t noticed any). This is why I have elected not to just hand out a new .jar, though I could happily do so under the MIT License. I didn’t then have the know-how to properly dig into the problem, and since lengthly debugging of broken applications is my full-time job right now, I’d rather not do so in my free time.

What You Will Need
Java Tools – Likely an IDE like Eclipse
Archiving Tools – 7Zip or a similar application for looking into the .jars
A copy of MARS.jar

Instructions
I’m going to assume you’re using Eclipse, because that’s all I know, so you may have to dig for some of the options if you’re using something else. I will assume you may never have encountered Eclipse or Java before though. Java is a lot like C#, but Eclipse is a bit different from Visual Studio. If you’re better at Java than me, do please let me know where I’ve done things the hard way round, and feel free skip the easy sections.

As another heads-up, I’m also using Windows, so this experience may be rather different for anyone hailing from the OSX or Linux world (I’m told that the creation of an executable .jar on Linux is free from some of the woes I encountered).

Project Setup
Firstly, create a new folder, open up Eclipse and select this folder as your workspace. I called mine ‘Mars_4_1_Mod’. You then need to create a new project in this workspace (File->New->Java Project). Name your project, and hit ‘Finish’. Note that my JRE is set to JavaSE1-1.7. This setting may be important – I’m not overly familiar with it myself.

Now right-click on the project in the Package Explorer, and select ‘Import’. You want to import the contents of MARS.jar to the project, so select General->Archive File from the dialog, browse to your copy of MARS, and hit ‘Finish. Your Package Explorer should now look something like this.

MARS_01

Finally, you need to make sure that Eclipse can find the source code in the project. To do this, right-click on your project and select ‘Properties’. Go to Java Build Path->Source, click ‘Add Folder’ and select your project root. You can fiddle with exclusions and stuff if you want, but I preferred the shotgun approach for what it’s worth.

The Fix
You should now be able to build and run the project (Run->Run As…->Java Application, select ‘Mars’ and hit ‘OK’). Mars should run normally and freeze as expected. Alternatively, if you run it via Run->Debug As…->Java Application then you will be able to suspend the application from Eclipse when it locks up, and then investigate the lock-up state for yourself from the Debug perspective.

Great, now go to ‘Navigate->Open Type…’ and use it to find your way to KeyboardAndDisplaySimulator.java. Navigate to line 210. It should look like this:

updateMMIOControl(RECEIVER_CONTROL, readyBitCleared(RECEIVER_CONTROL));

This is our culprit – a threading issue, a deadlock caused by this function call and another from AbstractMarsToolAndApplication.java. To implement the workaround as I have, you simply need to replace this line with the following:

//-------------------------------------------------------------------------------------
//This call caused a deadlock sometimes when using the keyboard and display simulator.
//The syncronized block below simply plucks out the necessary call from
//updateMMIOControlAndData, which is where this call would take us in the end.
//-------------------------------------------------------------------------------------
//updateMMIOControl(RECEIVER_CONTROL, readyBitCleared(RECEIVER_CONTROL));
//-------------------------------------------------------------------------------------
synchronized (Globals.memoryAndRegistersLock) {
   try {
      Globals.memory.setRawWord(RECEIVER_CONTROL, 0);
   } catch (AddressErrorException e) {
      e.printStackTrace();
   }
}
//-------------------------------------------------------------------------------------

Now if you run Mars through either Run or Debug you should find that the freeze-up never happens. Feel free to poke around if you want to know more about the original issue – but if you’re just trying to work with Mars for a personal project, this should be good enough.

Bonus
If you’re a student working on a project for your studies you may wish to provide your marking tutor with a copy of your modified MARS application alongside your assembly program. Now, after much pain I DO have a working .jar of this, and I will detail it’s creation beneath in case you run into difficulties as well, though it’s probably stupid because I’m not experienced enough with Java to know what exactly prevented me from doing it the normal way.

In the beginning it seems there are two options – you can export a Runnable .jar from Eclipse (File->Export->Java->Runnable JAR File – make sure to select ‘Package required libraries into generated JAR, ignore the warnings), or you can try running the script, ‘CreateMarsJar.bat’ which should be in the root of your project.

For me at least, the script somehow creates a .jar with the same bug as the original, and the exported ‘Runnable’ .jar…won’t run. The way around this is to make a copy of the original Mars.jar, open both it and your Eclipse-exported jar using 7Zip or a similar application, and copy the ‘mars’ folder (contains the compiled .class files) from your version into the copy of the original, replacing it’s own.Delete your exported jar and run the copy of the original – it should now perform as well as the version you launch from Eclipse.

Thanks and Stuff
Thanks go to my friend Bombpersons, without whom I might not originally have bothered to look into this issue. If you have any further information on this issue, any corrections to the information provided here, or struggles in doing this yourself, please do get in touch.

Kick Demon Cats to the Curb and go Beyond the High Score ◥▶̸̱◀◤

Okay. So there aren’t any demon cats yet, and that was my most desperate reference of the entire project, but this is a post about Mega Driller Mole, and I shall weather no more digressions.

Mega Driller Mole is a prototype Android game created for the Mobile Development module of my course at the University of Derby. The objective is to guide the mole around the screen using your finger, collecting minerals and avoiding mines, enemies (such as typically giant worms or the aforementioned demon cats), and other hazards. Combos build up as you collect more minerals without taking damage, and you must drop off your current load on the surface if you want to get any points out of it at all.

Moley McMolemole (doesn’t actually have a name) can currently run into three mines and then it’s game over, but if you’re good then the game could theoretically last forever, and your combo can get ever higher. Currently the difficulty doesn’t scale as the game progresses, and this is one of the things that will need fixing if the game is ever to hit the marketplace.

See, some friends of mine are setting up as a company this coming year while I’m (hopefully) off on placement, and while I won’t be joining them, I told them they can have this prototype and, if they wish, make something special out of it. I’ll probably end up helping them out, if only in an artistic capacity – since I’ve set such high standards – but it’s really up to them whether this goes forwards.

You can see some gameplay of the current version in the video above, where I show off awesome things, like, jumps and flips and stuff, and the awesome parallax scrolling, and the highly optimised, threaded particle system, and- and…just watch the video.

There are some obvious things missing – mineral varieties are one, along with graphics for the minerals and mines. Difficulty scaling will also be entirely crucial.  I’d also like to hide super valuable minerals in the bedrock and make it tunnelable (slowly), implement a ‘dug-out’ graphic for where the player has been, add second means to get more air (and hence more height bonus), enemies (demon cats and giant worms!), other power-ups, perhaps, and bonus score items.

Obviously I won’t be putting up source or downloads for this project since it may one day be put to commercial use, even if it may be released for free with ad support. Oh I should also mention that the game uses LibGDX, which is why it can be run under Windows, which is why you can see a mouse on the video up above, stepping into the shoes of touch control.

For now I’ll leave you with a little vector graphic I whipped up for the title screen, and head off to bed.

G’night!

Four days

I have an interesting timetable for university this semester, requiring that I attend lectures and tutorials only three days out of the week – and then only for a few hours at a time in the morning or afternoon. It’s rather different from last year’s timetables, which had lectures, tutorials and seminars scattered all over the place, and it took some getting used it. What it means, however, is that I have two afternoons, one morning, and then four full days who’s happenings are left entirely up to me. I really like it. Four days of no set timetable means I can work under my own conditions rather than being forced to work in the labs between lectures, and having just emerged from one of these long weekends I can report a small collection of successes which might not have happened if I was forced to work in a less comfortable environment.

In a recent post I mentioned I was going to be looking into Java in any spare time I got in my busy schedule, but that all changed last Thursday when we were told in Team Software Development that we had to create a Java recode of our C# / Silverlight project. My summer of experience with OpenGL has really paid off and I’ve been able to get pretty far on the back-end o the game, hiding away the OpenGL stuff with a class named Graphics, which will be passed around to Entities and contain ‘draw’ functions much like SpriteBatch in XNA. What this means is that the rest of my team won’t have to worry about the OpenGL implementation under the covers and should be able to just plow on with converting the game. To be honest I’d be pleased to carry on the project in Java alone – it’s a much nicer prospect than working with Silverlight through XNA and Silversprite, and it means we can use real perspective projection for our 2.5d gameplay, rather than faking it (Silversprite does not allow for 3D functionality). What this means overall is that I’ve had a kick-start in Java – I’ve found it to be rather nice, and it’s very easy to make the short leap from C#.

I’ve also made some progress with Pastry3D this weekend. While I began looking into scanline triangle rasterization as an alternative to using half-space equations, and even implemented it to some working extent, , I found the algorithm to be unwieldy and less flexible than my current solution, and opted to look into animating and texturing models instead. I’m happy to report success in these endeavors and the results will soon be added to the Pastry3D page in the form of screenshots and joyous ramblings.

MeTube

I was gonna mention this yesterday, but I figured one post was enough; I’ve fleshed out my new YouTube channel with a few old videos so that there’s actually something there to see. There’s a couple of old animations, some gameplay footage of Jetpack Paladin and Total Collapse, and a video of me playing Gremlins 2. Not a lot to be getting on with, but I’ll try to put up something more whenever I can.

In other news, I’ve started looking into Java as a potential platform for any future personal projects of mine. Java is simple, more portable than XNA, and learning another new programming language is always fun. University work has let up a bit for the time being, but assignments are soon to be set so I need to make the most of the next couple of weeks. I hope to multitask during my learning period in Java by also prototyping a secret project of mine, and building a usable backend so that at the next opportunity that presents itself I’m ready to start work on it. Still, that idea is going to remain conceptual for a long time, and I have another game to start work on soon with my friends here at home.

I’ve also been continuing my search for a work placement next year, and have come across some really interesting games in the process. Maybe I’ll post some information about that later on. As I write this I’m listening to a recent album by the chiptune composer RushJet1, who you should really check out if you’re into that sort of thing.