Author Topic: The Q-gears project *READ THIS FIRST*  (Read 25099 times)


  • Global moderator
  • No life
  • *
  • Posts: 2104
  • Karma: 20
  • NicoNico :)
    • View Profile
    • Q-Gears Homepage
The Q-gears project *READ THIS FIRST*
« on: 2006-05-12 03:38:42 »
As I have a Financial Management midterm to study for, I found it now to be the best time to completely ignore that and get the Q-gears forum up and running with a new sticky readme and FAQ.

So with much fanfare, I announce the Q-gears forum.

Please take the time to read the following if you are new here, it answers a lot of questions on what the project is about.

Part, the first.

What is Q-gears?
Q-gears is an attempt to make a clone of Squaresoft's Final Fantasy 7 game engine. It is designed to be cross-platform and run on modern operating systems such as Win32 and Linux. In the future this is to serve as a framework for compatibility with other Square games. Many games after this were created with the same same code base and design philosophy. Written in C++ and character scripting in LUA, it uses cross-platform graphics libraries (SDL and OpenGL) along with cross platform C/C++ compilers. It is named after "Gears" which is a wholly inaccurate and incredibly incomplete reference for the original FF7 engine. The "Q" means nothing, other than it's a cool letter to differentiate between the document and the program.

Why C++?
I was coerced. (^_^)

So I can download q-gears and play Final Fantasy 7 without buying the game?
No. The goal of Q-gears is to make a drop-in replacement for the Final Fantasy 7 executable. The main idea is to use data supplied by Square to play Final Fantasy 7. (This means you *MUST* have the original media to play Final Fantasy 7). You can however use our custom data or create your own data and levels! In a perfect world, this would be a pretty cool engine to use so you could make your own FF7-style engine by way of a Total Conversion. This is something waaay in the future though.

That sounds cool, how can I help?
Well, there are lots of things to do. First you should probably learn how the original Final Fantasy 7 works. You do this by grab a copy of the reference document, "Gears" from here.
You could also check out the wiki which is a much more organized and complete form of the Gears document minus the images.
This gives you an overview of the system, but it is woefully incomplete. It's enough to get you started on the system and is a cool read if you just want to know how the program ticks. For more information on Gears (the document), read Part, the second, later on.

After getting Q-Gears, and have an itch to code, you will want to download the latest Q-Gears source code form Github. Keep in mind that in this stage of the project, the code really doesn't do much but compile. However, you can see how we are laying everything out.

The GitHub page is here:
To get the code, you must follow the instructions at .  We recommend you fork the project if you want to make any changes since directly modifying the base is not allowed.  If you want your changes to be added to the base you should submit a pull request.

To download the source, dependencies and everything you need to compile you must follow the compilation instructions at:

How do I upload my changes?
Fork the project and make your changes, then submit a pull request and we will most likely add your changes.
(If you don't know what a pull request is, you should read this )

I can't program, can I help any other way?
Why yes, you can. As it stands right now, we are looking to help with Q-Gears!
What would be useful skill knowledge wise:
- Art/Modeling: Gimp/Photoshop/Blender/3d modeling/animation
- LUA/C++/XML scripting and programming languages (LUA is simple while C++ is harder, but most of the code will end up being in LUA. XML is used for formatting or defining data)
- Git/github
- Someone with a mac to test mac builds/help get the build working
- Being able to reverse stuff or just general FF7/8/9 knowledge

I can also use someone to help fill out the technical spec for FF7 in the wiki. That will require you know scour both here and the Tech-related forum for intresting gems of data, and then get that into the wiki to fix it's broken-ness. See Part, the second, for that.

Internet Relay Chat (IRC)
You can find the developers of Q-Gears on IRC most of the time if you want to help with the project:

Network:  EsperNet
Port:  6667

If you don't have an IRC client (I recommend you get one) you can use this alternative link:

How about Enhancements? I would like Bump mapping/MP3 Muisc/Per-pixel lighting/Particle effects....
No, as it stands right now, the clear goal is to get an engine up and running. Things like enhanced backgrounds, battle effects, and music are only considered if it's critical to the program. (For example, an increase in resolution to support newer systems.) We need it running as close to the original executables as possible. If you want to add your own effects or functions go ahead and fork the code and go wild. If it's orthogonal enough, we could add it back to the main trunk.  To merge your changes submit a pull request on GitHub

Can you make it mod friendly? How about some mod tools?
Q-Gears is planned to be very mod friendly (and it already is!), we use LUA wherever possible, an easy to learn scripting language for Field Script. The Wiki on the GitHub explains what the Field Commands are and what their parameters are (  The 3D-Models are in the OGRE format (there are plenty of tools to export/import to this) and the Menu module uses a combination of XML (like HTML) for formatting the menus and LUA to drive the options/selections.

Which port of FF7 are you supporting? The PC version? The PSX version?
Both would be nice, however, as for right now, the PSX dataset is the one activly being worked on. This is for serveral reasons.
First, it is by far the most common. The PC version is getting harder and harder to come by.
Second, as for me, I can work with the PSX data while it's running in a sandboxed environment. I can watch data get accessed in-situ and change it without the system knowing I've got my fingers in it.

Part, the second.

Holy mother of all that's good! Your Gears document is wholly inaccurate and incredibly incomplete!
Yea, I know. I haven't updated after I almost lost it in a very bad hard drive crash. But fear not. It is now in process of being converted to a wiki. Here you can update the information contained in Gears and add your own. Keep in mind, the wiki is even more incomplete and inaccurate than the Gears PDF file. One day, it will be the central repository for engine documentation.

The original Gears document can be found here:

The wiki can be found here:

Hey! I can't edit anything. Can I have write access?
If you have any good gems to add to the wiki, PM me with a username, a password, and an email address. I'll most likely add you.

Part, the third.
Taking it apart.

If you are more apt at taking things apart than putting things together, you can go to the tech-related topic on this very forum. Here we talk about disconstucting FF7 and understanding it's technology so we can put it back together again. I'm a mod there too.

Part, the fourth.

Hey, isn't this illegal? I mean, this sounds kind of like Chrono Trigger Resurrection, and that was shut down by Square.

No, because at the core of it all, Q-gears is just a virtual machine that does nothing without external game data, which is not included. The creation of virtual machines to play games is nothing new. Others exist, such as ScummVM, FreeSCI, Sarien, and Fortz. Making an implementation isn't illegal or else Linux wouldn't be around right now.

(Note: The IBM v. SCO lawsuit not withstanding. That lawsuit is a scam. The upshot is that SCO says that they own UNIX and Linux is an illegal derivative. However, it has been three years and SCO hasn't even told IBM *what* they have done that's illegal. It's just wasting time and hasn't even gone to trial. It's still in discovery. Sub-Note: Discovery takes about two months, not three years. Sub-sub-Note: The president of SCO hired his brother to represent the company during the lawsuit. The millions of dollars in lawyer fees goes from SCO to the brother. See? It's a scam.)

In the end, if a C&D letter comes down. It was a fun ride.

Part, the fifth.

(Things go here as I think of them)

Orthogonal: You keep using that word, but I don't think you know that it means

Orthogonal programming is a design philosophy that I adore. I picked up the idea from reading The Pragmatic Programmer: From Journeyman to Master. The book is available from I highly recommend this book for any programmer of any level. (As you can tell)

Orthogonal programming is best discribed by a quote in the book.

"Orthogonality is a critical concept if you want to produce systems that are easy to design, build, test, and extend. However, the concept of orthogonality is rarely taught directly. Often it is an implicit feature of various other methods and techniques you learn. This is a mistake. Once you learn to apply the principle of orthogonality directly, you'll notice an immediate improvement in the quality of systems you produce.

What Is Orthogonality?

"Orthogonality" is a term borrowed from geometry. Two lines are orthogonal if they meet at right angles, such as the axes on a graph. In vector terms, the two lines are independent. Move along one of the lines, and your position projected onto the other doesn't change. In computing, the term has come to signify a kind of independence or decoupling. Two or more things are orthogonal if changes in one do not affect any of the others. In a well-designed system, the database code will be orthogonal to the user interface: you can change the interface without affecting the database, and swap databases without changing the interface. Before we look at the benefits of orthogonal systems, let's first look at a system that isn't orthogonal.

A helicopter has four main controls: foot pedals, collective pitch lever, cyclic, and throttle. The foot pedals control the tail rotor. With the foot pedals you can counteract the torque of the main blade and, basically, point the nose where you want the helicopter to go. The collective pitch lever, which you hold in your left hand, controls the pitch on the rotor blades. This lets you control the amount of lift the blades generate. The cyclic, which you hold in your right hand, can tip one section of the blade. Move the cyclic, and the helicopter moves in the corresponding direction. The throttle sits at the end of the pitch lever.

It sounds fairly simple. You can use the pedals to point the helicopter where you want it to go. You can use the collective to move up and down. Unfortunately, though, because of the aerodynamics and gyroscopic effects of the blades, all these controls are related. So one small change, such as lowering the collective, causes the helicopter to dip and turn to one side. You have to counteract every change you make with corresponding opposing forces on the other controls. However, by doing that, you introduce more changes to the original control. So you're constantly dancing on all the controls to keep the helicopter stable.

That's kind of similar to code. We've all worked on systems where you make one small change over here, and another problem pops out over there. So you go over there and fix it, but two more problems pop out somewhere else. You constantly push them back—like that Whack-a-Mole game—and you just never finish. If the system is not orthogonal, if the pieces interact with each other more than necessary, then you'll always get that kind of distributed bug fixing.

In computing, the term has come to signify a kind of independence or decoupling. Two or more things are orthogonal if changes in one do not affect any of the others. In a well-designed system, the database code will be orthogonal to the user interface: you can change the interface without affecting the database, and swap databases without changing the interface."

FF7 is very modular. It's the philosophy that should be embraced. Keep everyone seperate and on modular paths with a common core. It will make things so much more helpful.

« Last Edit: 2015-04-30 20:02:44 by Tom »


  • Fast newbie
  • *
  • Posts: 16
  • Karma: 0
    • View Profile
Re: The Q-gears project *READ THIS FIRST*
« Reply #1 on: 2009-03-22 05:57:44 »
Am I allowed to reply to this?

Great idea. I know there are mods out there already that improve the game.

One goal is to make editing the game easier.


  • Guest
Re: The Q-gears project *READ THIS FIRST*
« Reply #2 on: 2009-07-11 11:25:39 »
Does the name gears come from how FF7 and Xenogears are kinda linked (both developed around the same time)?


  • Global moderator
  • No life
  • *
  • Posts: 2104
  • Karma: 20
  • NicoNico :)
    • View Profile
    • Q-Gears Homepage
Re: The Q-gears project *READ THIS FIRST*
« Reply #3 on: 2009-07-13 03:20:15 »
No, just sounded cool at the time.


  • Freak
  • *
  • Posts: 705
  • Karma: 30
  • King of the Spoilers
    • View Profile
Re: The Q-gears project *READ THIS FIRST*
« Reply #4 on: 2011-03-06 12:24:30 »
hey kinda new to the forums but I'm real excited for this, can't wait to see how the game runs on a more recently built engine. Keep up the good work!