Tutorial 1: Advanced Modding Techniques and Workflow

From WiCWiki

Jump to: navigation, search

Contents

by the Insane Buzzstards

Questions and Annotations

This tutorial can be discussed in this thread. Please help us making this tutorial as perfect as it can be, by giving hints and writing comments!

Introduction

The purpose of this tutorial is to introduce you into a modding-workflow that proved to be fast and efficient (at least for us ;)). We'll begin explaining some of the main-principles that we use and right after that we start with a step-by-step-tutorial (with pics!! yes. pics!!! got it?? pics!!!).

Separating mod-content from SDK

If you already took a look at the SDK you might or might not have realized, that the SDK is nothing but a big bunch of all types of files, which you simply edit. It is even a complete WiC-Installation. To test your mod, you start this WiC-Installation and see whatever happens. And if you are ready to give your fantastic mod to the community, you pack it into an sdf-file and ship it. Well ... wait. Which files do i pack into the sdf, you might ask yourself, because you have simply forgotten which files were changed by you and which not. Good question! So it would have been more clever, to create a separate mod-folder where you put all the files in, that you have changed. And to test your mod you simply copy those changed files into the SDK-Folder, but more about that later ...

Separating mod-logic from map-logic

Mapping and modding is hard to distinguish in WiC, because you do it in the same way: writing Python-Scripts and changing some other files. Separating mod-logic from map-logic means to choose the right place for the files you changed and scripts you wrote. You can write a whole total-conversion of WiC and put it into a map, but that's of course inefficient because you would do this for every map that is created for this total-conversion. So we encourage you to think about whether a class, method or whatever you write belongs to the mod-logic and so has to go into the mod, while the map just calls the methods of this mod.

The tools

In this tutorial we will use a whole bunch of tools that will make your modder-life a lot easier.
For scripting the python-scripts we use the programming-IDE Eclipse together with the plugin PyDev and additionally the python-debugging-helper PyLint. With the help of these tools you can debug your scripts before testing them with WiC, just to discover that you had a small typo which ruined your whole script. We will show you how to configure these tools in a way, that your modding and testing will be extremely fast and efficient.
Some sentences above, we wrote, that you need to copy the content of your personal mod-folder into the SDK-folder for testing. To make this step faster, we wrote the application "TheBluths" (honoring "Arrested Development", the best series in the world! god, please bring it back!). "TheBluths" automatically executes the copy-action for you by looking for file-change-events in the background.


Step I: Resource downloading

Before you can start with this tutorial you have to download the tools.

  1. Python (needed for debugging/compiling with eclipse)
  2. Eclipse Europe (download Eclipse Classic 3.3.1.1 or newer)
  3. PyLint
  4. TheBluths (you need the microsoft framework 2 installed )
  5. WiCPyS (Additional py-Files that were not included in WiC (needed for debugging))
  6. PyEncodingFix (also needs the MS .net framework 2)

Feel free to send bugs-reports or feedback for "TheBluth" and "PyEncodingFix" in the forum.

Step II: Component installation

Creating the folders

  1. Create an empty folder where you want to develop your mod, f. ex. "WiCModding". From now on we will call this folder "root".
  2. Install the WiC SDK (we recommend the tutorial-SDK with europeTest map) in this folder. We will call this folder "sdk-folder".
  3. Create a second folder where your mod-files will be placed in (remember, that we seperate the WiC SDK from our Mod-Files to have a cleaner structure?). Give it a name like "myMod" or whatever name your mod should have. We will call this folder "your modfolder".
  4. Exctract Eclipse (for users who only use Eclipse for wic-modding, we recommend to extract Eclipse in the root-folder)
    folder_structure.jpg

Installing Python and PyLint

  1. Run the pyton installer ("python-2.5.1.msi") and install it. Restart you computer when finished.
  2. Extract the "pylint.zip" to a temporary folder (later you can delete this folder).
  3. For the four extracted folders from the pylint package, find the "setup.py" and run it with the "install" argument (go to "run" and paste the file location of "setup.py" in quotation-marks and add "install" after it ... see the pic)
    pylint_install.jpg
  4. Now you can delete the pylint-folder.

Installing PyDev in Eclipse

  1. Start Eclipse (On the first start, Eclipse asks for the workspace. Browse to the root-folder. You can select the option to remind the workspace-location for the next start)
    eclipse_workspacelauncher.jpg
  2. When you run eclipse the first time, you will see a strange startpage. Select the workbench sympol.
    eclipse_startupselect.jpg
  3. In the menubar, select "Help" -> "Software Updates" -> "Find and Install..."
    eclipse_softwareUpdate.jpg
  4. Select "Search for new features to install"
    eclipse_pydev_install_00.jpg
  5. Click on "New Remote Site" and type "PyDev" for the name and "http://pydev.sourceforge.net/updates/" for the URL.
    eclipse_pydev_install_01.jpg
  6. Make sure that PyDev is selected and click on "Finish".
    eclipse_pydev_install_02.jpg
  7. Expand PyDev and make sure that "PyDev Optional Extensions" is NOT selected.
    eclipse_pydev_install_03.jpg
  8. Accept the licence conditions
    eclipse_pydev_install_04.jpg
  9. Click on "Install All" and you are finished
    eclipse_pydev_install_05.jpg

Configuring PyDev

  1. Go to the Eclipse preferences
    eclipse_conf_pydev_01.jpg
  2. Open the "PyDev"-node and select "Interpreter - Python"
    eclipse_conf_pydev_02.jpg
  3. Click on "New" (next to "Python Interpreters") and browse to your python-installation-directory and select "python.exe".
    eclipse_conf_pydev_03.jpg
  4. On the next window click on "Ok"
    eclipse_conf_pydev_04.jpg
  5. Open the "Pylint"-page in the "PyDev"-node
  6. Activate "Use Pylint?"
  7. Click on "Browse" and browse to "YOUR PYTHON-FOLDER/Lib/site-packages/pylint/lint.py"
  8. Copy the following text in the argument textfield: "--disable-msg=C0301,C0103,R0903,E0611,E1111,R0902,W0603,R0912,R0915" (without quotationmarks) (this will disable some annoying warnings and errors, that are somehow senseless for us)
    eclipse_conf_pydev_05.jpg

Configuring Eclipse

  1. Go to the Eclipse preferences (well ... you should still be there ...)
  2. Open the "General"-node and select "Workspace"
  3. Activate the "Refresh automatically"-option (this refreshes your project contents, when you change something from outside of Eclipse)
  4. Click on "Okay"
    eclipse_conf_01.jpg

Step III: Project Setup

Creating a new Eclipse project

  1. Click on "File" -> "New" -> "Project..."
    eclipse_newproject_01.jpg
  2. Select "Pydev Project" in the "PyDev"-node and click on "Next"
    eclipse_newproject_02.jpg
  3. Type the name for your project (in our case "myMod" ... the folder you created some minutes ago), select the python version (in our case it is python 2.5) and activate the option for creating the "src" folder.
    eclipse_newproject_03.jpg

Copying the necessary files from the SDK-folder to your mod-folder

Although you can do a lot with Python-scripting, you still need some other programs, like the Juicemaker. Unfortunately Juicemaker can just open files that are in one of its subfolders. So we have to copy some files from the sdk-folder.

  1. Copy all single files from the sdk-folder (files that are not in a subfolder of the sdk-folder) to the "src"-folder of your modfolder
  2. Copy the "python"-folder from the sdk-folder to the "src"-folder of your modfolder
  3. Copy the "maps"-folder from the sdk-folder to the "src"-folder of your modfolder (including the maps)
    eclipse_srcsetup_01.jpg
  4. Extract the WicPyS-package somewhere and place the files from the package in your modfolder (NOT in "src") *
    eclipse_srcsetup_06.jpg
  5. And last but not least: it is a good idea to make a backup of your SDK-folder, so that you still have a clean SDK somewhere for your second mod or whatever. So copy your sdk-folders content, except the big sdf-files somewhere for a backup

What are the WiCPyS???

Unfortunately, the WiC-SDK doesn't provide all necessary python-scripts, probably for security-reasons. The WiCPyS are fake-files for those missing scripts, so that you don't get errors when debugging with Eclipse. WiC itself somehow has these files somewhere internally. At the moment they are still empty, so you will still get some errors, that there are methods missing in these files. We will try to add fake-methods, so that all errors disappear.

Add file-filters to the Eclipse-Navigator

Now that you have copied all the files to your modfolder, they all appear in the navigator-window of eclipse making the project quite untidy. We have to tidy it up by adding filters to the navigator.

eclipse_srcsetup_02.jpg

  1. Go to "YOUR_ECLIPSE_FOLDER\plugins\org.python.pydev_1.3.10" and open up "plugin.xml"
    eclipse_srcsetup_03.jpg
  2. Search for "commonFilter" and place the code from this Tutorial 1: Eclipse Filter-page after the other Common-Filters
  3. Restart Eclipse with the parameter "-clean" and see the effect
    eclipse_srcsetup_04.jpg
    eclipse_srcsetup_05.jpg

Add Python-Paths to PyDev

When debugging your py-scripts with eclipse you need to add some paths to the python-system-path, so that the debugger finds the necessary files for the imports.

  1. Go to the Eclipse preferences
  2. Open the "PyDev"-node and select "Interpreter - Python"
  3. Click on "New Folder" next to "System PYTHONPATH"
  4. Browse to your modfolder and click on "Ok"
  5. Click on "New Folder" (again)
  6. Browse to "src/python" of your modfolder and click "Ok"
    eclipse_srcsetup_07.jpg

Fix the encoding of the WiC-Python Scripts

Some of the python-scripts that are coming with the sdk contain characters which are not defined in the default encoding-settings of the python-compiler. WiC ignores these problems, but we want to compile the scripts with the help of Eclipse. We wrote a simple program called "PyEncodingFix" which fixes this problem by inserting the correct encoding-information at the top of each script.

Copy the "PyEncodingFix.exe" in your mod-folder and execute it.

eclipse_srcsetup_08.jpg

Setting up "TheBluths"

With the help of "TheBluths" you will save yourself the copying-effort, because the application does this for you. You need to set-up two tasks. From your modfolders "src"-folder to your sdk-folder. And from the sdk-folders "maps"-folder to your modfolders "src"-folders "maps"-folder (god, what a sentence ...).

eclipse_thebluth_01.jpg

You can also add filters for the operation, so that specific file-types will NOT be copied when changed. You should, f. ex. add ".pyc". These are compiled python-scripts that eclipse creates and that are not needed in your sdk.

eclipse_thebluth_02.jpg

Now you have two tasks that react to file-actions in the background. You have to press "Start Observing" to make this working.

eclipse_thebluth_03.jpg

If you accidentally forgot to start "TheBluths" and changed some files, then you can synchronize the task-folders by using the "Start Sync"-Button. We recommend to synchronize directly after you added the tasks, so that everything is up to date!

Starting WiC from Eclipse

To make things easier, you can start WiC directly from Eclipse.

  1. Select "Run" -> "External Tools" -> "Open External Tools Dialog..."
    eclipse_external_01.jpg
  2. Double-Click on "Program" (Or Right-Click and "New")
    eclipse_external_02.jpg
  3. For the name type "Start WiC"
  4. Click on "Browser File System" under "Location" and browse to your SDK-folders "wic.exe"
  5. For the "Working Directory" paste the same path, just without the "wic.exe"
  6. And for the "Arguments" insert: "-debug -dev -console -map europeTest" (without quotation-marks) ... we will explain these later. You can also start with the "-mmap europeTest" parameter for multiplayer modding
    eclipse_external_03.jpg
  7. Go to the "Common"-Tab and select "External Tools" at the "Display in favorites-menu"-field
    eclipse_external_04.jpg
  8. Click on "Apply" to save it
  9. To start Wic all you have to do is to press the small green button with the red bag or whatever ... right to the other green button. clear? yepp.
  10. You can do it also with the other tools (note that the "JuiceMaker" must be started from your mod-folder)
    eclipse_external_05.jpg

Separating mod-logic from map-logic

Remember that we said it is good to separate mod-logic from map-logic??? if not ... scroll up and read that part again. In the end you will have your own python-scripts with your own methods and you will call these methods from the maps-scripts ("server.py", "client.py", etc.) and wic-python-scripts. Of course you will sometimes just change some of the normal python-scripts to your need, but the best way is to put all of your changes in your own scripts. And what is even more clever is to make your own python-scripts-folder instead of using WiC's python-scripts-folder.

Making an own folder for your mod-files

  1. Right-Click on your "src"-folder in the Eclipse Navigator
  2. Select "New" -> "Folder" and give it a prefix of your modname plus "_python". Here you will place your personal scripts.
  3. Go to the PyDev preferences and add this folder to the "System PYTHONPATH" (for the Eclipse-Compiler)
    eclipse_xxxx_01.jpg

You need to add this folder to the WiC-PYTHONPATH as well, otherwise WiC won't be able to import your modules. This means that you need to add this path in one of the scripts that WiC loads. We are still not sure in which order WiC loads its python-scripts, but the "clientimports.py" seems to be one of the first scripts to be loaded.

  1. Open up the "clientimports.py" in Eclipse and paste the following code at the beginning:
  import sys
  sys.path.append("mymod_python") 

The path is the name of the folder you previously created.

The python-root-folder of WiC is the folder, from which the exe is started (so the sdk-folder). If you had a subfolder in "mymod_python" where your scripts are, then you would need to append "mymod_python/subfoldername". okay? right.

Starting scripting

Congratultaions, you are now ready to start your modder-life! To compile a script in Eclipse, simply press F9. PyLint adds cool Warning and Error-markers on the sides of your scripts. Unfortunately it sometimes has a strange behaviour (at least for the scripts, that WiC already provided). If you do not see the warning-signs, try changing the file, save it and press F9 again.

If you want to check your script on every save, then activate "Project" -> "Build Automatically"

Forget about SDF-Files

Remember that you start your WiC with the parameter "-map mapName"??? When you specify this parameter, then WiC directly loads the map that you added after "-map", f. ex. "europeTest". With this parameter, you can test your whole mod. WiC uses the py-scripts in the SDK-folder (the ones you may have changed), compiles those to pyo-files and uses them in the game.

THERE IS NO NEED TO CREATE ANY SDF-FILE WHEN YOU DEVELOP!!!. The sdf-files are just for shipping your mod or map. you don't need to create them, when you develop your mod.

Some Debugging Tips

Annoying PyLint-Warnings

PyLint is a little bit too accurate. If there is a message, that annoys you, because it is senseless, then go to the PyDev-preferences, open up the "PyLint"-page and in the "Arguments"-field add the identification-code of the warning/error to the already existing list.

DebugMessage

When you start WiC with the parameters "-debug" and "-dev" (as we did above), the game will write the python-errors to a debug-text-file located in "My Documents/World In Conflict/Debug". It also creates a message-box that will be shown, when a python-error occures.

You can also print something into the debug-file by using DebugMessage("text"):

  import debug
  debug.DebugMessage("something happened")

Unfortunately you have to return to windows to look into the file to see your message. So this is just helpful, when your game really crashes and you want to find out when.

Using the ingame-console for output

You can use the ingame-console (^) to print your own debug-messages. You have to start WiC with the parameter "-console". You need to change the OnInit-method of your maps "client.py" in the following way:

  import sys, wic
  
  def OnInit():
     sys.stdout = wic.player # for print-output
     sys.stderr = wic.player # for python-errors
     print "test"            # print something to the console

Whenever you call print, the text will be redirected to your ingame-console. Great for debugging!

Using the ingame-console for input

You can even use the ingame-console for calling python-methods or any other python-command. All you have to do is to call the python-command with the prefix "py " and hit return.

Example:

  py print "This will be printed!"

Using the Debug-Viewer aka wic-viewer

The debug-viewer is also very interesting. Read Massive's Chapter about the debug-viewer here: http://wiki.massgate.net/Debug_Viewer In the coming days, we will provide our own debug-viewer, which makes it a bit easier to add your own commands to the viewer and keep everything tidy.

Personal tools
User Created Content