developers Introduction Guide

From OpenKore Wiki
Jump to navigation Jump to search

What this guide is

This guide was created to help people who already have experience with programming with getting started on Kore development.

What this guide is not

This guide is not meant for people who have no programming experience at all.

It would be an advantage if you already have the following knowlege:

  • Understanding of the difference between a compiled and interpreted language.
  • Understanding of network programming.
  • Some experience with DOS or command lines.

Contents

Introduction to open source

OpenKore is open source. This means that:

  • The source code is available for everybody to read and modify.
  • Open development is encouraged. Everybody can contribute code.

The most important reason why OpenKore is open source, is because the original Kore (by Kura) was also open source, distributed under the GNU General Public License. So all derived works (skore, OpenKore, all other Kores) must also be open source. You may want to learn the history of OpenKore before reading this page.

Advantages

Being open source is a huge advantage for OpenKore. Here are are some examples:

Active development

People were actively contributing code on (s)Kore's forums, such as new features and bug fixes.

Not dependend on the original author

The original author, Kura, stopped developing Kore. However, because the source was available, other people took the code and kept maintaining it. So even if the original author doesn't work on it anymore, other people can keep it alive. This is why Solos Kore exists. It soon became the most popular version of Kore.

Fast

Solos isn't maintaining Solos Kore anymore. When Comodo came to iRO, the protocol has changed and broke Solos Kore. Within one day, an inofficial bug fix was already available. This is how FakQ's mod, and later skore-revamped, and yet later OpenKore, were born.

Peer review

This is an important one, and is usually forgotten by many people. Everybody can read the source code, thus pointing out potential flaws. Backdoors and keyloggers won't last long, even if they can get in at all!

Myths

If you're coming from the MS Windows world, filled with commercial software, freeware and shareware, all without source code, then open source must seem very odd to you. Here are some common myths:

"People will steal your code and claim it as their own."

In theory, this is possible. But in practice, it almost never happens. Look at popular open source projects such as Linux, GNOME, KDE and OpenOffice: I have yet to see somebody "stealing" their code and claim the code as his own. Most people play by the rules, give credit to the original authors, and release the source code.
In case somebody does try to claim it as his own, it won't be a disaster. He will most likely be flamed down by the community for being a fraud. Nobody will use his version. It won't take long before he'll disappear.
Besides, you really don't need the source code to claim someone's software as your own! Everybody can open your executable in a hex editor, and change your name to his.

"People will put viruses and trojans in it"

You don't need the source code to put viruses and trojans in executables. So not providing the source code does not help at all. See also next point.

"An evil person can put in a backdoor or keylogger"

This is false. Everybody can modify the source code, yes. But that doesn't mean that everybody can get those changes into the official version! If somebody submits code, it will be reviewed by many people. Code with backdoors or keyloggers will get detected, and won't appear in the official version.

Everybody can contribute code. But that doesn't mean their code will blindly be accepted.

Programming language

OpenKore can be split into several components:

Component Programming language Notes
Main program:
  • openkore.pl
  • functions.pl
  • *.pm
Perl
Pathfinding, DLL injection (X-Kore), and more.
  • XSTools.dll (Windows)
  • XSToos.so (Linux/Unix)

(The source code is found in src\auto\XSTools)

C/C++ Some things in Kore are written in C or C++, for the following reasons:
  • Performance. Parts that do a lot of calculation are optimized in C++.
  • Some features are not directly available in Perl. Some techniques used by X-Kore mode use very low-level Windows API calls, and can only be implemented in C or C++.

XS is the native C-to-Perl glue. You can write stuff in C/C++ but provide a Perl API through XS.

The following things are implemented in XSTools:

  • Pathfinding calculation. It used to be written 100% in Perl, but that was (literally) 100 times slower.
  • DLL injection functions, used by X-Kore mode.
  • Platform-specific functions, such as a wrapper for ShellExecute() on Win32.
  • Various other utility functions.

Because of performance reasons, the most performance-critical parts are written in C++ (such as pathfinding).

Network data interception and redirection.
  • NetRedirect.dll

Source code (found in src\auto\XSTools\win32):

  • netredirect.cpp
  • utils-netredirect.cpp
C++ Used by X-Kore mode. This DLL is injected into Ragexe.exe's process space, and intercepts all incoming and outgoing network data, and redirects some of it to Kore. This makes it possible for Kore to control the Ragnarok Online client.

About Perl

Perl (Practical Extraction and Reporting Language or Pathologically Eclectic Rubbish Lister) is an open source, cross-platform, interpreted, programming language. It's main strength is string handling and parsing. Regular expressions makes it extremely easing to manipulate strings. You rarely have to worry about memory management since a lot of it is done automatically for you. It's syntax may be weird at first (compared to other languages, like C++, Pascal, Basic, etc.), but once you know it, you'll find out it's actually quite powerful. Perl, if used properly, is a very productive language.

Although Perl is an interpreted language, it can be "compiled". Kore uses ActiveState PerlApp (part of ActiveState Perl Dev Kit) to produce a Win32 binary. Compilation is only done by developers when they release a version to the public, since you can't expect all Windows users to install a Perl interpreter. There's no reason for developers to compile openkore.pl every time they make a change; it's much easier to run openkore.pl directly from the Perl interpreter. Linux users can run openkore.pl directly. Most Linux distributions come with a Perl interpreter by default.

Documentation

Learning Perl is a good online book which introduces you to the Perl programming language.

Other Perl documentation:

  • The Perl CD Bookshelf has links to other online Perl books.
  • Perldoc - Perl core documentation
  • CPAN - API documentation for many Perl modules and builtin functions

The IRC channel #perl at irc.freenode.net is a good place to get help if you can't figure out something. If you have a Kore-specific question you could ask at our forums.

If you have and don't know where to get a Perl interpreter/compiler, see Setting up the development environment.

More information about XS:

About C++

If you're a developer then it's unlikely that you haven't heard of C++ already. There are many books about C++, try looking at your local library. And if you don't want to read a book for whatever reason, try these websites:

XSTools.dll and NetRedirect.dll should be compilable by any standards-compliant C++ compiler. But the recommended compiler is GCC (part of Cygwin). See also Setting up the development environment.


How to use ActivePerl and GCC

How to use ActivePerl

Perl is a command-line based application. This means you'll have to run it from a DOS box/command prompt. Here's a crash-course command prompt in case you don't know how to use it.

Let's say you've written this Perl script, and saved it to the file C:\Documents and Settings\hello.pl:

print "Hello World!\n";

Now you must launch a command prompt. Click Start->Programs->DOS Prompt (Win9x), or Start->Programs->Acessories->Command Prompt (Win2k/XP). You will now see a big black window with white text, similar to Kore's console.

You also see that the line the cursor is at begins with "C:\>". This is the command prompt's working directory. You can compare it with the Location bar in a Windows Explorer window.

hello.pl is stored in C:\Documents and Settings. To change the working directory, use the cd "(FOLDER NAME)" command. This is similar to browsing to another folder in Windows Explorer. The following example shows how to change the working directory to C:\Documents and Settings:

C:\> cd "C:\Documents and Settings"
C:\Documents and Settings> _

You can now tell Perl to run hello.pl with the command "perl (YOUR SCRIPT'S FILENAME)". For example:

C:\Documents and Settings> perl hello.pl
Hello World!
C:\Documents and Settings> _

So, if you want to run openkore.pl, you first have to tell the command prompt to change the working directory to whatever folder that contains your openkore.pl. Then you type perl openkore.pl [arguments to pass to openkore], like this:

C:\> cd "C:\My Downloads\openkore"
C:\My Downloads\openkore> perl openkore.pl

Another example:

C:\My Downloads\openkore> perl openkore.pl --config=control/another-config.txt

How to use GCC

Like Perl, GCC is also a commandline program.

To compile XSTools.dll and NetRedirect.dll, you must use the Cygwin Bash shell. Grossly oversimplified, Bash is like DOS, except the directory seperated is a / instead of \.

First, cd into your OpenKore folder:

cd "C:/My Downloads/openkore"

Now type:

make

Yes, that's it.

If you see no error messages, then the compilation succeeded. You will find the DLLs in src\auto\XSTools.


So, what now?

Uhm yeah great, now you know how to use Perl, but what now? That might be what you're thinking right now. Here are some things that you can do.

Fix a bug

As with all software, OpenKore has bugs too. All bug reports are stored at the OpenKore Bugzilla (our bug tracking database).

Suggest and/or implement a feature

If you have a cool feature in mind, then you may want to discuss it on the forums, and/or implement it.

'The TODO list

Do you need something specific, but don't want to fix bugs? Then you may want to take a look at the OpenKore TODO list. Some items aren't even coding tasks or technical tasks.

How to submit code

Put your code between [CODE][/CODE] UBB tags, or attach it as a file. The former is preffered.