Lucky Survivor - Modders Guide

Main

Changing/Adding text/images

This does not require any programming knowledge.

This is the easiest way to make changes to the game. At any point while playing the game you can open a text/image editor (by default with Ctrl-t/Ctrl-i respectively) and change the texts/images currently shown in the game. You can add/change/delete alternatives. If there is more than one alternative the game will randomly pick one of them.

When you make text changes, don't forget to push the "Save" button. Changes you make in the image editor are saved automatically.

The changes you make are immediately visible in the game and they are stored in the "mod" directory.

If you would like to share your changes with others and get them integrated in the main game, just zip up your "mod" folder and post it on the Futanaripalace message board. Once all your changes are integrated in main game, you can delete your "mod" folder.

Adding simple events

Still no programming knowledge required.

An event editor is being worked on that will let you create new events from within the game.

From advanced events to changes in the game engine

Program it yourself or convince a game developer to do it for you, which is not that difficult, if what you want done is good.

Setting up development environment

-- Fuck it! We'll do it live!

All the required software is freely available for all common computer platforms (Windows/Mac/Linux).

The game is written in Java using Eclipse as IDE, git for SCM and github to exchange sources between game developers.

Java
The requirements are the same as for running the game (Java 7 SE), except you must install the JDK
Eclipse
I recommend you get "Eclipse IDE for Java Developers" from http://www.eclipse.org/downloads/.
git
"Eclipse IDE for Java Developers" already comes with EGit which IMHO is the best choice anyways, as it integrates directly in the IDE:
github
You need to create a free github.com account.
The following steps are:
  1. Create a ssh key pair and upload the public key to github. The github website should guide you how to do this.
  2. When logged in to github, goto https://github.com/Lehirti/Lehirti-Game-Engine and create a fork (There is a "Fork" Button). At /Lehirti/Lehirti-Game-Engine everyone has read access, but only i have write access. Everyone will have read access to the fork you create, but only you will have write access.
  3. Once the clone is created (at something like https://github.com/[Your Username]/Lehirti-Game-Engine) start Eclipse.
  4. You now need to create a local clone of your own github project. See http://www.vogella.com/articles/EGit/article.html#github on how to do this
  5. At one point you will be able to select the existing projects to import. You can choose all of them, but LehirtiEclipsePlugin is not required (it's a started project, but it does nothing, yet and development is on hold).
  6. Copy the "core", "config" (& "mod") dirs from a regular game installation into the "LuckySurvivor" project root dir (same level as "src") and create the folder "mod/events/bin".
  7. Right-click LuckySurvivor->run->LuckySurvivor.launch Run As->LuckySurvivor to start the game and verify that everything is working.
Congratulations. You have successfully set up the build environment. Now you can start hacking.

HOW-TO add a new event

This taken from a forum post explaining to hasori - the story guy - how he can add "Startscreen" event before the then first event of the game.
  1. In project "LuckySurvivor" open package intro
  2. Copy Airport.java into the same package. New name: Startscreen.java
  3. Open Startscreen.java
    change this
    public class Startscreen extends EventNode<NullState> {
      public static enum Text implements TextKey {
        AIRPORT_DESCRIPTION,
        OPTION_ENTER_BUS,
        OPTION_SKIP_INTRO;
      }
      
      @Override
      protected ImgChange updateImageArea() {
        return ImgChange.setBG(IntroImage.AIRPORT);
      }
      
      @Override
      protected void doEvent() {
        setText(Text.AIRPORT_DESCRIPTION);
        
        addOption(Key.OPTION_ENTER, Text.OPTION_ENTER_BUS, new Bus());
        addOption(Key.OPTION_LEAVE, Text.OPTION_SKIP_INTRO, new Plane1_YourSeat());
      }
    }
    
    to
    public class Startscreen extends EventNode<NullState> {
      public static enum Text implements TextKey {
        STARTSCREEN_DESCRIPTION,
        OPTION_START;
      }
      
      @Override
      protected ImgChange updateImageArea() {
        return ImgChange.setBG(IntroImage.STARTSCREEN);
      }
      
      @Override
      protected void doEvent() {
        setText(Text.STARTSCREEN_DESCRIPTION);
        
        addOption(Key.OPTION_ENTER, Text.OPTION_START, new Airport());
      }
    }
    
    and save Startscreen.java
  4. Set the cursor in the word IntroImage and press F3. IntroImage.java will be opened. add a new constant with the name "STARTSCREEN" and save IntroImage.java
  5. Open Main.java. In line 22 change the ending: "new Airport()" to "new Startscreen()". Press Ctrl-Shift-o (or right click on the underlined Startscreen and select "import ..."). Save Main.java
  6. Now there should be no compile errors (red decorators on the left). Start Main.java and you should be greeted with an empty screen where you can add the Stony-faced intro image and some text before the game starts with Airport event.
  7. Once everything works as intended, right-click on the LuckySurvivor Project on the left. Select Team->Commit ...
    A commit dialogue should pop up where you have to enter a commit message (e.g. "Startscreen added") and select which files to add to the commit (think of a commit as a snapshot of the game sources in its current state).They should not be offered anyways, but DO NOT add texts or images (anything from within "core" or "mod" folders) to commits. the git repository is for sources only.
    Your commit should consist of:
    1. New: Startscreen.java
    2. Changed: Main.java
    3. Changed: IntroImage.java
    Select those and hit "commit" (with this you save the snapshot locally)
  8. Right-click LuckySurvivor Project: Team->Push to Upstream (with this you make your local changes available for others (me))

The Island Map

This is current version of the entire island in one image: Island Map

Beautifications of the map should be made to this one-image version from which the in-game map is derived. Creating the game resources from the "one-image" version is currently a manual process and takes ~1 hour, so any improvements to the map should worth the effort.

In-game the map is cut into tiles. To the player the map will always look like one continuous map, but in reality the will only ever be tiles which are 4 times as large as what's visible on screen. Island Map with Grid

One of the black rectangles in the above image is the size of what's visible on screen at a time, but the map will always be centered on the current location/path, so it looks continuous to the player. The coordinate (0,0) is where the top-most and left-most black lines meet. Some other coordinates have been drawn into the image to illustrate how the coordinate system works.

When the player first enters the island map, it's on tile (0,3). Every location delimited by the rectangle (0,3), (1,3), (0,4), (1,4) uses this tile as the background image. The red rectangle shows the actual size of tile (0,3).

The formula is:
x
(X-Pixels - 200)/400
y
(Y-Pixels - 150)/300

If you want to change an existing location or add a new one, the whole tile business does not concern you. All you have to do is: open LuckySurvivor/src/map.Map and add/modify a line like this:

public class Map extends EventNode<NullState> {
  public static enum Location implements TextKey, ImageKey {
    CRASH_SITE(0.55, 3.45, new StaticEventFactory(MapToCrashSite.class)),
    CLIFF_WEST(0.45, 3.35, new StaticEventFactory(MapToCliffWest.class)),
    JUNGLE_1_UPHILL(0.65, 3.25, new StaticEventFactory(MapToJungle1Uphill.class)),
    ...

The first two numbers in the Location constructor (e.g. the "0.55" and "3.45" after "CRASH_SITE(") are the x and y coordinates of the location. The game engine will take care of the rest. If you add an Image for the Location, this image will be used to draw the location. Note: Location images must have both a "Scale X" and a "Scale Y" value. Otherwise an X will be drawn.