MININIM Source Code Study

A free software implementation of Prince of Persia 1.
Nick2017
Sheikh
Sheikh
Posts: 30
Joined: January 7th, 2017, 10:45 pm

MININIM Source Code Study

Post by Nick2017 »

Hi,

I would like to know how are the objects (kid, guards, spikes, etc.) of the game animated. Is there some kind of timer that count's CPU cycles so that when certain amount of cycles passed the next frame of the animation is displayed? also, how are the frames and objects loaded into memory? using arrays? linked-lists?

Thanks!
User avatar
oitofelix
Wise Scribe
Wise Scribe
Posts: 227
Joined: February 17th, 2016, 1:59 pm
Location: Brazil
Contact:

Re: MININIM Source Code Study

Post by oitofelix »

Welcome to the forum, Nick2017. :)
Nick2017 wrote:I would like to know how are the objects (kid, guards, spikes, etc.) of the game animated.
The first thing to keep in mind is that MININIM uses the Allegro low-level game programing library. It's really the only non-trivial dependency of MININIM. Allegro (and the standard C library, of course) is the interface MININIM uses to interact with almost anything in the system. Therefore, the way that library is designed determines to a reasonable extent how MININIM handles its tasks, specially the low level ones. Fortunately, it's a well designed library. :roll: Said that, the core module you are looking for is the animation module "anim.c". It handles several tasks related to animation, but its main (primordial) function is play_anim.

Code: Select all

void play_anim (void (*draw_callback) (void), void (*compute_callback) (void))
Within that function you'll find the application main event processing loop. The parameters of that function are generic callbacks for drawing and computing whatever is needed. Callers should provide both routines (or pass NULL, in case one isn't needed), and play_anim takes care of when and how to call them. The function play_anim is a generic routine; it's used for both cutscene and in-level animations. The first thing you have to ask yourself is which of them are you primarily interested in. They have similarities, but many differences too. For in-level animations, play_anim is called by play_level (level.c). Studying its provided callbacks along with play_anim is a good starting point.

Nick2017 wrote:Is there some kind of timer that count's CPU cycles so that when certain amount of cycles passed the next frame of the animation is displayed?
MININIM uses Allegro timers for that. The main timer which determines the game's so called "time cycles" is pointed by the global variable timer of the anim.c module. However, Allegro timers are a concept that pretty much only the animation module knows about. The flow of time for the rest of the game (character actions, level physical events, ...) is governed by the global variable anim_cycle (uint64_t), which is incremented at each tick of the animation timer.
Nick2017 wrote:also, how are the frames and objects loaded into memory? using arrays? linked-lists?
For each character action there is a "struct frameset" array in its respective module (basically one module per action), that holds the bitmaps of each frame of animation and their "standard" relative offsets.

Almost all MININIM types are defined in the types.h header. Look there for exactly what a "struct frameset" is, and then look into an action module, like "kid/kid-run.c" (which governs the kid's running animation and logic), for a practical understanding of how they are used.


Good luck with your MININIM source code study! Let me know any further questions you might have.

PS 0: Let's take this in homeopathic doses. I could go on and on, rambling about things... :P I'll just give you some initial pointers and thoughts (cause time won't allow me to write too much in one take). You can look things yourself based on what I've told you and/or ask specific questions about what you want to know. I know initially, while you are trying to get started and wrapping your head around it, it's difficult to formulate specific questions. However, keep always in mind that the more specific the better (for everybody). ;) It's very hard to understand and to make yourself understood speaking in an abstract manner. The devil in the details. :twisted:

PS 1: Debugging MININIM with GDB is a very good way to learn how MININIM works from the inside out.
Bruno Félix Rezende Ribeiro (oitofelix)
MININIM author
Nick2017
Sheikh
Sheikh
Posts: 30
Joined: January 7th, 2017, 10:45 pm

Re: MININIM Source Code Study

Post by Nick2017 »

Hi oitofelix, thanks for you reply. I've been looking at the code for about 3 hours and I haven't made too much progress... :( I've been thinking about it and I figured the best way would be to dismantle the code. With this I mean to remove all the code that it's not necesary to play animations and leave the bare minimum code. I've never done anything like this before, so it would be a huge learning experience for me. This way I can go through each function and document what they do, because the code is not documented. But first I have to be able to compile the code, so I need to install some GUI and of course the compiler. As soon as I figure this out I'll start with this.
User avatar
oitofelix
Wise Scribe
Wise Scribe
Posts: 227
Joined: February 17th, 2016, 1:59 pm
Location: Brazil
Contact:

Re: MININIM Source Code Study

Post by oitofelix »

Nick2017 wrote:I've been looking at the code for about 3 hours and I haven't made too much progress... :(
Please, don't be discouraged, that's normal. If you spend enough time looking at and playing with the code, familiarity will emerge naturally.
Nick2017 wrote:I've been thinking about it and I figured the best way would be to dismantle the code. With this I mean to remove all the code that it's not necesary to play animations and leave the bare minimum code.
Well, that could work, after all I also started with the animations. However, dismantling a 50k+ lines program is quite a challenging task, arguably only rivaled by assembling those 50k+ lines from scratch ;). My opinion is that after the program has been built, the best way to confront its complexity is using a good debugger. Have you looked at debugging it with GDB?
Nick2017 wrote:I've never done anything like this before, so it would be a huge learning experience for me.
I sincerely hope so. May I ask what's your background? What's your experience with C programming and computers in general?
Nick2017 wrote:This way I can go through each function and document what they do, because the code is not documented.
If you succeed at acquiring enough understanding of MININIM's source code to document it properly, I'd be glad to assist you on an official source code documentation reference. That could be part of MININIM's manual. By the way, MININIM project is in need of a good documentation writer, because I'm too busy implementing new features and fixing bugs at the moment. Currently the manual lags far behind the available features. I see you have a good command of English, so if you want to help with that, you're very welcome as well.
Nick2017 wrote:But first I have to be able to compile the code, so I need to install some GUI and of course the compiler.
Surely! There is no way to gain in-depth understand of a non-trivial program without being able to enter the loop "modify, build and run/debug it".

What's your system? Free software matters aside, any variant of the GNU system is an ideal environment for developing MININIM. That's what I use: Debian GNU/Linux. For that effect any Unix-like will do, but you'll need to work at least with the GNU development toolchain to be able to build MININIM (for example, MinGW on Windows).

Feel free to ask questions here about any issue you may need help with.
Bruno Félix Rezende Ribeiro (oitofelix)
MININIM author
Nick2017
Sheikh
Sheikh
Posts: 30
Joined: January 7th, 2017, 10:45 pm

Re: MININIM Source Code Study

Post by Nick2017 »

oitofelix wrote:Have you looked at debugging it with GDB?
Nope, its for linux only, Am I right?
oitofelix wrote:I sincerely hope so. May I ask what's your background? What's your experience with C programming and computers in general?
I'm an Electronics Engineer and I also have a degree in programming, but it's only related to banking software which is very boring... that's why I'd like to learn about game programming.
oitofelix wrote:If you succeed at acquiring enough understanding of MININIM's source code to document it properly, I'd be glad to assist you on an official source code documentation reference. That could be part of MININIM's manual. By the way, MININIM project is in need of a good documentation writer, because I'm too busy implementing new features and fixing bugs at the moment. Currently the manual lags far behind the available features. I see you have a good command of English, so if you want to help with that, you're very welcome as well.
Great, I would like to help!
oitofelix wrote:What's your system?
I'm using Windows 7. I've installed CodeBlocks and the Allegro libraries. But right now it says it can not find a header called "argp.h". I'll have to see how to fix that...
User avatar
oitofelix
Wise Scribe
Wise Scribe
Posts: 227
Joined: February 17th, 2016, 1:59 pm
Location: Brazil
Contact:

Re: MININIM Source Code Study

Post by oitofelix »

Nick2017 wrote:
oitofelix wrote:Have you looked at debugging it with GDB?
Nope, its for linux only, Am I right?
Not really. GNU software is available on a wide variety of platforms, including Windows. For instance, MinGW-W64 provides GDB binaries.
Nick2017 wrote:
oitofelix wrote:If you succeed at acquiring enough understanding of MININIM's source code to document it properly, I'd be glad to assist you on an official source code documentation reference. That could be part of MININIM's manual. By the way, MININIM project is in need of a good documentation writer, because I'm too busy implementing new features and fixing bugs at the moment. Currently the manual lags far behind the available features. I see you have a good command of English, so if you want to help with that, you're very welcome as well.
Great, I would like to help!
That's great! Did you take a look at MININIM's PDF manual bundled with releases? It's written in Texinfo. If you are serious about documentation you probably should learn it. It's like TeX but arguably easier. However, if you don't want to, you could help by writing good documentation in plain text, and then let the job of integrating it within the manual to me or other possible future volunteer.

You could start by gathering information about new features (there are various posts throughout princed.org about them), then testing and exploring them, then discussing any questions that might arise with me, and finally writing about it, in a formal, technical but approachable way. Try to follow the style of the existing documentation. (Of course, that is not set in stone. I'm open to discuss any suggestions for improvement you may have.)

Multi-room and replays are examples of two major features that are still undocumented. There are many other things to cover as well.
Nick2017 wrote:
oitofelix wrote:What's your system?
I'm using Windows 7. I've installed CodeBlocks and the Allegro libraries. But right now it says it can not find a header called "argp.h". I'll have to see how to fix that...
That's because MININIM requires gnulib to reproduce such GNU C library functionality on Windows.

I'd not be hopeful about the prospect of building MININIM using CodeBlocks. Many aspects of it requires a GNU system, including its building infrastructure. If you insist in using Windows for MININIM development, I recommend you use MinGW-W64. (that's what I use on Debian for cross-compiling to Windows)

PS: If you have a sufficiently capable computer, a virtual machine running GNU/Linux would save you much time and trouble.
Bruno Félix Rezende Ribeiro (oitofelix)
MININIM author
Falcury
Calif
Calif
Posts: 565
Joined: June 25th, 2009, 10:01 pm

Re: MININIM Source Code Study

Post by Falcury »

I also use the MinGW-w64 toolchain to compile stuff on Windows.
Unfortunately their binary distributions (and the SourceForge website especially) are a horrible mess... at least for me it look me a long time to figure out what I had to install, and how to put everything in the correct places.

For reference, these are (roughly) the steps that I use myself:

Download either of the following .7z packages with the MinGW-w64 binaries for Windows, depending on whether you want to compile to 32-bit or 64-bit executables (the links below correspond to the "Mingw-builds" distribution on this page).

For targeting x86 (32-bit):
https://sourceforge.net/projects/mingw- ... six/dwarf/

For targeting x86_64 (64-bit):
https://sourceforge.net/projects/mingw- ... posix/seh/

Just unpack the archive, and put the directory inside it in a convenient location (ideally put the folder at the root of your hard drive, e.g., "C:/mingw64").

Then, you have several options:
  • Compile using an IDE, like Code::Blocks for instance. Much of the time, this may be the most straightforward approach. There should be a setting somewhere to set the path to your toolchain binaries (that would be "C:/mingw64/bin" for instance). If your IDE is using its own 'internal' toolchain/compiler thingy, you will probably be able to force it to use MinGW-w64 instead.
  • Compile directly from the command line. To be able to call the toolchain utilities from any working directory, add the MinGW-w64 binaries directory (e.g., "C:/mingw64/bin") to the PATH environment variable. (To edit the environment variables on Windows 7, I simply press the Windows key, type "environment", then pick the Control Panel option "Edit environment variables for your account")
Nick2017
Sheikh
Sheikh
Posts: 30
Joined: January 7th, 2017, 10:45 pm

Re: MININIM Source Code Study

Post by Nick2017 »

Well... I've installed mingw64 and I'm still getting the same message "argp.h: No such file or directory"... where can I download this file?
User avatar
oitofelix
Wise Scribe
Wise Scribe
Posts: 227
Joined: February 17th, 2016, 1:59 pm
Location: Brazil
Contact:

Re: MININIM Source Code Study

Post by oitofelix »

Nick2017 wrote:Well... I've installed mingw64 and I'm still getting the same message "argp.h: No such file or directory"... where can I download this file?
In the official build procedure, the bootstrap script takes care of that. The relevant invocation is:

Code: Select all

gnulib-tool --source-base=gnulib --m4-base=gnulib/m4 \
--aux-dir=gnulib/build-aux --import error vasprintf argp strcasestr progname glob
Notice the argp module being imported there.

As I said, you can find gnulib here. However, to bootstrap and configure MININIM you'll need a POSIX compatible shell (probably you'll need GNU Bash itself) and GNU Autotools (Autoconf, Automake, et al). After that the source code tree (or the build tree, for VPATH builds) should be ready for compilation using GNU Make.

PS: I'm skeptical about the practicality of building MININIM without a minimal GNU system, (like the one MinGW provides with MSYS).
Bruno Félix Rezende Ribeiro (oitofelix)
MININIM author
Nick2017
Sheikh
Sheikh
Posts: 30
Joined: January 7th, 2017, 10:45 pm

Re: MININIM Source Code Study

Post by Nick2017 »

I have no idea what you are saying... this is why I don't like unix/linux, because they make a simple task extremely complicated...
User avatar
oitofelix
Wise Scribe
Wise Scribe
Posts: 227
Joined: February 17th, 2016, 1:59 pm
Location: Brazil
Contact:

Re: MININIM Source Code Study

Post by oitofelix »

Nick2017 wrote:I have no idea what you are saying... this is why I don't like unix/linux, because they make a simple task extremely complicated...
In some cases, but in this particular instance I think it's the other way around. Notice that if you were using a GNU system (under virtual machine or otherwise), you probably would already have built MININIM long ago, and wouldn't be facing this much trouble. You had been warned.

If you are interested in starting doing things the easy way, let me know. ;)
Bruno Félix Rezende Ribeiro (oitofelix)
MININIM author
Nick2017
Sheikh
Sheikh
Posts: 30
Joined: January 7th, 2017, 10:45 pm

Re: MININIM Source Code Study

Post by Nick2017 »

I managed to download the argp.h and progname.h, but now I'm getting a bunch of warnings and errors when I try to compile, so I think it will be better to try your style. I also found that one of my laptops has Fedora 3.19 installed, will that one work? if not I'll try the Virtual Machine with some linux image, right?
User avatar
oitofelix
Wise Scribe
Wise Scribe
Posts: 227
Joined: February 17th, 2016, 1:59 pm
Location: Brazil
Contact:

Re: MININIM Source Code Study

Post by oitofelix »

Nick2017 wrote:I managed to download the argp.h and progname.h, but now I'm getting a bunch of warnings and errors when I try to compile
That's expected. MININIM's build system is responsible for preparing the source tree for compilation. Such task is not trivial and cannot be obviated by the inclusion of just a few headers.
Nick2017 wrote:so I think it will be better to try your style.
I'm glad you are wiling to pursue your goal. :)
Nick2017 wrote:I also found that one of my laptops has Fedora 3.19 installed, will that one work? if not I'll try the Virtual Machine with some linux image, right?
Is that a recent version? It's best (that's fewer potential problems) if you stick with a recent one. Any distribution having Allegro 5.2.0 or superior in its repository should be fine. Actually it could be as low as 5.0.10, but then you'd have to build a more recent version of Allegro yourself (that's easy, because their dependencies are the same) if you are interested in some new MININIM features that will be release soon. Probably I can help you the most if you use Debian.
Bruno Félix Rezende Ribeiro (oitofelix)
MININIM author
User avatar
Norbert
The Prince of Persia
The Prince of Persia
Posts: 5743
Joined: April 9th, 2009, 10:58 pm

Re: MININIM Source Code Study

Post by Norbert »

oitofelix wrote:
Nick2017 wrote:I have no idea what you are saying... this is why I don't like unix/linux, because they make a simple task extremely complicated...
In some cases, but in this particular instance I think it's the other way around.
Yes, GNU/Linux basically already includes a solid programming environment. On Windows it's more complicated to get things up and running; requires more manual work. Nick2017 might simply be used to Windows. Generally speaking, GNU/Linux does not make simple tasks complicated, it makes complicated tasks simple. The command-line interface is also a powerful thing. Using it isn't required, but the more you know about it, the more you may like it. Bash and its tools are so important to me that I can understand why Windows 10 started offering programmers a way to use them.
User avatar
oitofelix
Wise Scribe
Wise Scribe
Posts: 227
Joined: February 17th, 2016, 1:59 pm
Location: Brazil
Contact:

Re: MININIM Source Code Study

Post by oitofelix »

Norbert wrote:Bash and its tools are so important to me that I can understand why Windows 10 started offering programmers a way to use them.
That's GNU taking over the world. :twisted:
Bruno Félix Rezende Ribeiro (oitofelix)
MININIM author
Post Reply