Skip to content

Commit

Permalink
Update first part of README
Browse files Browse the repository at this point in the history
  • Loading branch information
@szapp
szapp committed Sep 13, 2017
1 parent 31b042b commit 05fc38c
Showing 1 changed file with 106 additions and 214 deletions.
320 changes: 106 additions & 214 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,10 +3,30 @@ Gothic Free Aim

**Script package for the video games Gothic and Gothic II that enables free aiming for ranged weapons and spells.**

**Note**: This is source code for developers. If you are interested in a playable version instead, checkout this
modification [Gothic II - Freies Zielen](http://forum.worldofplayers.de/forum/threads/1482039) (German language).
[![Trailer on Youtube](http://i.imgur.com/1smu8Az.jpg)](http://www.youtube.com/watch?v=9CrFlxo21Qw)

[![Trailer on Youtube](http://i.imgur.com/PhJ3gcm.jpg)](http://www.youtube.com/watch?v=9CrFlxo21Qw)
Here is a list of playable modifications featuring this script package (all available in
[Spine](http://forum.worldofplayers.de/forum/threads/1499872)):

- Gothic - Freies Zielen (comming soon)
- [Gothic II - Freies Zielen](http://forum.worldofplayers.de/forum/threads/1482039)
- Gothic II - Free Aiming (comming soon)
- [RespawnModEnhanced](http://forum.worldofplayers.de/forum/threads/1493169)
- [Dirty Swamp 2.0](http://forum.worldofplayers.de/forum/threads/1490097) (coming soon)

<br/><br/>

Contents of this Readme
-----------------------

1. [Features](#features)
2. [Installation](#installation)
3. [Project Architecture](#project-architecture)
4. [Customization](#customization)
5. [Debugging](#debugging)
6. [Contact and Discussion](#contact-and-discussion)

<br/><br/>


Features
Expand All @@ -15,96 +35,108 @@ Features
- Free aiming for ranged weapons (bows, crossbows)
- Free aiming for spells
- Shot projectiles (arrows, bolts) can be picked up and re-used
- Dynamic critical hit detection (e.g. head shots)
- Modifiable hit registration by different criteria (surface material and texture)
- True shooting accuracy
- Critical hit detection (e.g. head shots)
- Modifiable collision behavior by different criteria
- Movement during aiming
- True shooting accuracy by scattering
- Draw force (projectiles drop faster if the bow is not fully drawn)
- High customizability (see **Examples** and **Customization** below)

**Examples**

Here short list of some examples which are easily implementable (or already included) in `config\`. There is a lot
more freedom, however.

- Change the way the draw force (projectile gravity) is calculated (by weapon stats, skill level, ..)
- Change the way the accuracy is calculated (by weapon stats, skill level, ..)
- Change the initial damage when an arrow is shot (by draw force, accuracy, skill level, ..)
- Change the reticle style (by draw force, accuracy, weapon, aiming distance, enemy, ..)
- Different critical hit zones (body parts like head, torso, limbs) (by guild, weapon, ..)
- Different damage for critical hits
- Notification when getting a critical hit (sound, screen print, ..)
- *Head shot* counter that gives XP every 25 head shots.
- Disable friendly-fire for quest/party members
- Define collision behavior of projectiles by surface material or texture (e.g. arrows break or deflect when hitting
stone or get stuck in wood)
- Change the projectiles when they have been shot (e.g. used arrows that need to be repaired)
- Enable/Disable retrieving projectiles (e.g. the player first has to learn to retrieve arrows from animals)
- And much more. Get creative!
- High customizability with easy to use configuration
<br/>


Installation
------------

Again, this is the installation **for developers**. If you are interested in a playable version instead, checkout this
modification [Gothic II - Freies Zielen](http://forum.worldofplayers.de/forum/threads/1482039) (German language).
#### Requirements:

Requirements:
| Gothic | Gothic II: Night of the Raven |
| :--------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------- |
| | [Reportversion 2.6.0.0](http://www.worldofgothic.de/dl/download_278.htm) |
| [G1 Mod Development Kit (MDK)](http://www.worldofgothic.de/dl/download_28.htm) | [G2 Mod Development Kit (MDK)](http://www.worldofgothic.de/dl/download_94.htm) + [patch 2.6a](http://www.worldofgothic.de/dl/download_99.htm) |
| [Ikarus 1.2](http://forum.worldofplayers.de/forum/threads/1299679) | [Ikarus 1.2](http://forum.worldofplayers.de/forum/threads/1299679) |
| [LeGo dev-branch](https://app.assembla.com/spaces/lego2/subversion/source/HEAD/dev) until supported | [LeGo 2.4.0](http://lego.worldofplayers.de) or higher |

- Gothic II: Night of the Raven ([Reportversion 2.6.0.0](http://www.worldofgothic.de/dl/download_278.htm))
- [Mod Development Kit (MDK)](http://www.worldofgothic.de/dl/download_94.htm) with scripts
(+ [patch 2.6a](http://www.worldofgothic.de/dl/download_99.htm))
- [Ikarus 1.2](http://forum.worldofplayers.de/forum/threads/1299679)
- [LeGo 2.4.0](http://lego.worldofplayers.de) or higher with HookEngine, FrameFunctions and ConsoleCommands

A [setup](http://github.com/szapp/GothicFreeAim/releases/latest) is available to take care of the integration. Just run
it, and all scripts should be fully working (originals will be backed up). Alternatively, you can do these following
steps manually.
#### Installation Steps:

1. Make sure Ikarus and LeGo are installed and parsed with _work\data\Scripts\Content\Gothic.src`.
1. Make sure Ikarus and LeGo are installed and parsed with `_work\data\Scripts\Content\Gothic.src`.
2. Copy all files from this repository into your Gothic II installation. Mind the relative paths. Do not forget the
binary files (textures) that come with the [release](http://github.com/szapp/GothicFreeAim/releases/latest).
3. Have the files parsed:
1. Add the line `FREEAIM\freeAim.src` to `_work\data\Scripts\Content\Gothic.src` somewhere **after** Ikarus, LeGo
and `AI\AI_INTERN\FOCUS.D`.
1. **[GOTHIC 1]** Add the line `FREEAIM\freeAim_G1.src` to `_work\data\Scripts\Content\Gothic.src` somewhere
**after** Ikarus, LeGo and `ANIMS\FOCUS.D`.
**[GOTHIC 2]** Add the line `FREEAIM\freeAim_G2.src` to `_work\data\Scripts\Content\Gothic.src` somewhere
**after** Ikarus, LeGo and `AI\AI_INTERN\FOCUS.D`.
2. Add the line `camera\caminstfreeaim.d` to the end of `_work\data\Scripts\System\Camera.src`.
3. Add the line `Pfx\PfxInstFreeAim_G2.d` to the end of `_work\data\Scripts\System\PFX.src`.
3. **[GOTHIC 1]** Add the line `Pfx\PfxInstFreeAim_G1.d` to the end of `_work\data\Scripts\System\PFX.src`.
**[GOTHIC 2]** Add the line `Pfx\PfxInstFreeAim_G2.d` to the end of `_work\data\Scripts\System\PFX.src`.
4. Add the line `sfx\sfxinstfreeaim.d` to the end of `_work\data\Scripts\System\SFX.src`.
5. Add the line `visualfx\visualfxfreeaim.d` to the end of `_work\data\Scripts\System\VisualFX.src`.
6. Add the line `menu\menu_opt_game_freeaim.d` to `_work\data\Scripts\System\Menu.src` between `_intern\menu.d` and
`menu\menu_main.d`
4. Add a new menu entry to the options game menu. Extend the instance `MENU_OPT_GAME` in
`_work\data\Scripts\System\Menu\Menu_Opt_Game.d` with these two lines just before
`items[XX] = "MENUITEM_GAME_BACK";`.

```
items[XX] = "MENUITEM_OPT_GFA";
items[XX+1] = "MENUITEM_OPT_GFA_CHOICE";
```

Where `XX` is the index. Of course, increase `XX` to `XX+2` for `MENUITEM_GAME_BACK`. With this you can enable and
disable free aim from the options menu.
5. In the same file change `posy = MENU_BACK_Y;` in the instance `MENUITEM_GAME_BACK` to `posy = MENU_BACK_Y+300;`.
This repositions the menu entries such that everything fits.
6. Set the constant `MENU_ID_GFA` in `Menu_Opt_Game_FreeAim.d` to the next available slot in the menu, typically
4. Add a new menu entry to the options game menu. With this you can enable and
disable free aim from the options menu. Keep in mind, that there are still players preferring keyboard controls
over mouse. Without this setting you drive away a fraction of potential players!
1. Extend the instance `MENU_OPT_GAME` in `_work\data\Scripts\System\Menu\Menu_Opt_Game.d` with the following two
lines just before `items[XX] = "MENUITEM_GAME_BACK";`, where `XX` is the index. Of course, increase `XX` to `XX+2`
for `MENUITEM_GAME_BACK`.

```
items[XX] = "MENUITEM_OPT_GFA";
items[XX+1] = "MENUITEM_OPT_GFA_CHOICE";
```

2. In the same file change `posy = MENU_BACK_Y;` in the instance `MENUITEM_GAME_BACK` to `posy = MENU_BACK_Y+300;`.
This repositions the menu entries such that everything fits vertically.
3. Set the constant `MENU_ID_GFA` in `Menu_Opt_Game_FreeAim.d` to the next available slot in the menu, typically
`(XX-1)/2`. For example:

```
const int MENU_ID_GFA = 7; // Next available Y-spot in the menu
```
```
const int MENU_ID_GFA = 7; // Next available Y-spot in the menu
```
4. You might have to adjust the labels in `_work\data\Scripts\System\Menu\Menu_Opt_Game_FreeAim.d`. By default they
are in German.

7. Initialize free aim by adding the line `GFA_Init(GFA_ALL);` in to the function `INIT_Global()` in
`_work\data\Scripts\Content\Story\Startup.d` either somewhere *after* Ikarus and LeGo or *instead* of them.
**[GOTHIC 1]** If you do not have the function `INIT_Global()` yet, create it and call it from all `INIT_*()`
functions.
8. Add the lines as indicated in `_work\data\Anims\Humans.mds.additions` into `_work\data\Anims\Humans.mds`. Do the
same analogous for `_work\data\Anims\MDS_Overlay\Humans_BowT2.mds.additions` and
`_work\data\Anims\MDS_Overlay\Humans_CBowT2.mds.additions`.
9. Delete the files `_work\data\Anims\_compiled\HUMANS.MSB`, `_work\data\Anims\_compiled\HUMANS_BOWT2.MSB` and
`_work\data\Anims\_compiled\HUMANS_CBOWT2.MSB`.
**[GOTHIC 1]** You might have to start the game twice for the animations to fully work.

After parsing the scripts, GFA should be fully implemented. Read on to find out how to adjust GFA to your preferences.

7. Finally initialize free aim by adding the line `GFA_Init(GFA_ALL);` in to the function `INIT_GLOBAL()` in
`_work\data\Scripts\Content\Story\Startup.d` either somewhere *after* Ikarus and LeGo or instead of them.

> Again: The [setup](http://github.com/szapp/GothicFreeAim/releases/latest) will perform all these steps for you.
#### Usage (Important!):

By using these scripts, you agree to the terms of the **[MIT License](http://opensource.org/licenses/MIT)**.
Please respect my efforts and accredit my work in your project accordingly, i.e.
> This modification utilizes Gothic Free Aim, (C) Copyright 2016-2017 mud-freak (@szapp).
> < http://github.com/szapp/GothicFreeAim >
> Released under the MIT License.
If you omit this, you are stating this was your own work which is effectively violating the license.

<br/>


Project Architecture
--------------------

This diagram shows how all the functions of GFA are connected. When not otherwise specified, arrows denote one function
calling another. The left column represents the engine, the middle shows the internal functions of GFA and on the right
are the configuration functions. To understand the architecture, it is recommended to read from right to left (config ->
wrapper functions -> unterlying mechanics -> engine hooks). Features are color coded (see legend). This is a vector
graphic: Open it in your web browser and zoom in to read everything.

You will have to adjust the labels in `_work\data\Scripts\System\Menu\Menu_Opt_Game_FreeAim.d`. By default they are in
German. After parsing the scripts GFA should be fully implemented. Read on to find out how to adjust GFA to
your preferences.
![Project architecture](https://rawgit.com/szapp/GothicFreeAim/master/architecture.svg)

> **Note**: By using these scripts, you agree to the terms of the **[MIT License](http://opensource.org/licenses/MIT)**.
Please respect my efforts and accredit my work in your project accordingly (i.e. *"This modification utilizes Gothic
Free Aim written by mud-freak (@szapp)"* in the credits). If you omit this, you are stating this was your own work which
is effectively violating the license.
<br/>


Customization
Expand Down Expand Up @@ -254,6 +286,8 @@ This list of conditions works without exception with all Gothic 2 tNotR spells a
conditions (which will make them inconsistent across all Gothic spells) all newly created spells should meet/not meet
these conditions, because they make sense.

<br/>


Debugging
---------
Expand Down Expand Up @@ -282,154 +316,12 @@ above).
- Whether focus collection is enabled (ini-file setting for performance)
- Whether projectiles are enabled to be reusable
- Whether free aiming is enabled for spells


Project Architecture
--------------------

This diagram shows how all the functions of GFA are connected. When not otherwise specified, arrows denote one function
calling another. The left column represents the engine, the middle shows the internal functions of GFA and on the right
are the configuration functions. To understand the architecture, it is recommended to read from right to left (config ->
wrapper functions -> unterlying mechanics -> engine hooks). Different features are color coded (see legend). This is a
vector graphic: Open in your web browser and zoom in to read everything.

![Project architecture](https://rawgit.com/szapp/GothicFreeAim/master/architecture.svg)


Unfinished Features
-------------------

These features were not fully implemented.

- Strafing while aiming
- Bow draw animations while aiming

Attempts, progress and unstable implementations for both features are available in the branches `strafing` and
`drawAni`. Keep in mind that they are far behind `master`. If you think you can finish these features, feel free to
create a pull request. Consult with the issue tracker for information on possible limitations and different attempts.


FAQ
---

Q: **Do balancing issues arise from GFA?**

A:
No. The option, to collect/re-use projectiles, however, increases the amount of arrows/bolts (since the player will need
less of them). This should be kept in mind. If you disable this features, there is absolutely no impact on balance.

Q: **Is there an easy way to try and get a feel for this script?**

A:
Anyone can try the free aiming by downloading the demo modification (see link above). This can be done without much
effort. Note that this demo is in German.

Q: **How do I install GFA into my scripts?**

A:
You can find the latest release [here](http://github.com/szapp/GothicFreeAim/releases/latest). Follow the instructions
above.

Q: **I am getting an error while parsing: *"Syntax error :  ( line 1 )"*, what now?**

A:
In the zSpy log you should see which file was parsed last, before the error occured (presumably `Startup.d`). Open the
file and save it with the encoding *ANSI (Windows-1252)*.

Q: **I am getting and error telling me *"CC_Register"* is missing, what now?**

A:
Your version of LeGo is out dated: GFA requires LeGo 2.4.0 or higher.

Q: **It does not work? What now?**

A:
Should the installation of GFA fail, please read through this README.md first. If this does not help, post your
problem into the mentioned forum thread (see **Contact and Discussion** below) with the following information:

- What exaclty is not working: Is the game not launching (list possible parser errors)? Is nothing happing in the game
(as if GFA was not installed)? Does the game crash (when and how)?
- Attach possible error messages/codes
- Attach the zSpy log
- If possible, please post the output when entering `GFA info` into the F2-ingame-console.

Q: **Why does my game crash?**

A:
See **"It does not work? What now?"**. Additionally, it will be essential to describe your configuration, ideally by
attaching your files in `freeAim\config\`.

Q: **What is the deal with the license? May I use GFA in my modification?**

A:
In the section **Installation** above, I have written what the license implies. Please read it, keep it in mind and
respect it. If you see a modification making use of this script and not mentioning it in the credits, feel free to
remind the creator of that mod of the license conditions or report them to me.

Q: **Why is the reticle not in the center of my screen?**

A:
You seem to be using version v0.1.0 of GFA. Update it to the
[latest version](http://github.com/szapp/GothicFreeAim/releases/latest).

Q: **Why do I have a rock-like texture instead of a reticle on my screen?**

A:
You seem to have missed the textures. You can download them
[here](http://github.com/szapp/GothicFreeAim/releases/latest).

Q: **How can I define critical hit zones for different monsters?**

A:
In the default configuration the critical hit zones are defined very loosely as the head for all NPCs. This should be
adjusted if possible, since these definitions are very inaccurate. This has not been done to not conflict with mods that
do not include all monsters from Gothic II and to encourage you to put in a little work yourself. Nevertheless, well
defined critical hit zones (head for all native Gothic II creatures) are available in the
[mod scripts](http://www.worldofgothic.de/?go=moddb&action=view&fileID=1330) of the demo modification
*"Gothic II - Freies Zielen"*. Furthermore, in order to design your own critical hit zones, I created a script to help
with that. You can find it in the forum thread linked in the section **Contact and Discussion** below.

Q: **Is this script still being developed?**

A:
No, it is complete. See **Future** and **Contact and Discussion** below for more information.

Q: **I have a great idea for a feature! Could you implement it, please?**

A:
See **Future** and **Contact and Discussion** below for more information.

Q: **(I think) I have found a bug. How can I report it?**

A:
You can report bugs either in the forum thread or to me directly via the information in the section
**Contact and Discussion** or create a ticket directly here in the Github Issue Tracker. A good bug report should
include the following information:

- Detailed description of what happened.
- Detailed description of how it happened.
- Output when entering `GFA info` into the F2-ingame-console.
- zSpy Log.
- The Access Violation message (if applicable).
- Your configuration (attach the files in `freeAim\config\`).
- Used versions of Ikarus/LeGo.
- If possible: Your own attempts to isolate and reproduce the bug.


If your question is not listed here, please read through this README.md first, before posting into the forum thread or
asking for help (see **Contact and Discussion**).
<br/>


Contact and Discussion
----------------------

Head over to the [World of Gothic Forum](http://forum.worldofplayers.de/forum/threads/1473223) to share your thoughts or
questions that you might have or to join the discussion about this script. It is easiest to keep everything in one
place.


Future
------

This script will not be worked on after 2016. Nevertheless, feel free to create **pull requests** if you implement new
features.
questions that you might have or to join the discussion about this script. Forum language is German or English. It is
easiest to keep everything in one place.

0 comments on commit 05fc38c

Please sign in to comment.