Skip to content

Commit

Permalink
Update README.md for next release
Browse files Browse the repository at this point in the history
  • Loading branch information
Van-Ziegelstein committed Jun 10, 2018
1 parent 62941b9 commit 7740355
Showing 1 changed file with 20 additions and 16 deletions.
36 changes: 20 additions & 16 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,22 +24,21 @@ metadata saved in another file labeled `resources.assets`. Users wishing to repl
with something else will have to overwrite the `resources.assets.resS` file with a new one and
update the aforementioned metadata.

Shadow-Tune aims to automate this replacement process. However, it is **not** a music converter and it is
*Shadow-Tune* aims to automate this replacement process. However, it is **not** a music converter and it is
up to the user to provide a properly formatted `resources.assets.resS` file.

## Why does this exist?
Shadow-Tune 1.0 was originally developed as part of the effort to bring the Shadowrun Hong Kong mod *CalFree in Chains*
*Shadow-Tune* `1.0` was originally developed as part of the effort to bring the UGC campaign [CalFree in Chains](https://steamcommunity.com/sharedfiles/filedetails/?id=1239356669)
(which every self-respecting Shadowrunner should play if he/she/it hasn't already) to Linux platforms. The mod came with its
own soundtrack and a Linux-specific solution was needed to properly apply it and restore vanilla behavior once finished with the campaign.

Shadow-Tune 2.0 is the extended version of the original, capable of applying the same replacement operation to Shadowrun Returns
and Shadowrun Dragonfall as well. It is the hope of this particular decker that this script will be useful in some way to
future users/modders and that we will see many new UGC campaigns in the years to come. Shadowrunners unite!
*Shadow-Tune* `2.0` is the extended version of the original, capable of applying the same replacement operation to *Shadowrun Returns* and *Shadowrun Dragonfall* as well. It is the hope of this particular decker that this script will be useful in some way to future users/modders and that we will see many new UGC campaigns in the years to come.

Shadowrunners unite!

## Prerequisites
- A Perl interpreter, preferably `>= 5.26.2`.
Most Linux and Unix flavors should come with one pre-installed. Windows users might want to give Strawberry Perl or ActivePerl
a try. (**Note: At this point, Windows portability of the script is not guaranteed! See below for further info.**)
Most Linux and Unix flavors should come with one pre-installed. Windows users might want to give [Strawberry Perl](http://strawberryperl.com/) or [ActivePerl](https://www.activestate.com/activeperl) a try. (**Note: Only Strawberry Perl has been tested so far. See [Limitations](#limitations) for further information.**)

## Installation
Download the latest version from the [Release](https://github.com/Van-Ziegelstein/Shadow-Tune/releases) page or clone the repo.
Expand Down Expand Up @@ -75,16 +74,16 @@ game can be specified with this switch.

`-i <path-to-shadowrun-install-folder>`

The script comes with some glob patterns that it uses to locate the Shadowrun games. It is not unlikely for this
The script comes with OS-specific glob patterns to locate the Shadowrun games. It is not unlikely for this
process to fail, though, and this commandline option can be used to manually point the script to the Shadowrun game that is to be modified.

Pitfalls:

-The path given with the `-i` switch should just lead to the root directory of the installation, e. g.
`/some/folders/Shadowrun Dragonfall Director's Cut` or `/some/folders/Shadowrun Hong Kong`.
`/some/folders/Shadowrun Dragonfall Director's Cut` or (for the Windows cmd) `c:\Program Files (x86)\some\folders\Shadowrun Hong Kong`.

-The specified game directory must correspond to the game selected with the `-e` switch. (E.g. if **only** `-i`is used
to point to the location of Shadowrun Dragonfall **without** setting `-e` to the appropriate value, the script will disgard
to point to the location of *Shadowrun Dragonfall* **without** setting `-e` to the appropriate value, the script will disgard
the path.)

`-v`
Expand All @@ -93,19 +92,24 @@ Obtain more verbose output.

## Screenshots

| Parsing resources.assets of Shadowrun Returns | Parsing a new resources.assets.resS file | Updating resources.assets of Shadowrun Hong Kong |
| Parsing resources.assets of Shadowrun Returns | Parsing a new resources.assets.resS file | Updating resources.assets of Shadowrun Hong Kong |
| --- | --- | --- |
| <img src="screenshots/shadow_tune1.png" width="250" height="400"/> | <img src="screenshots/shadow_tune2.png" width="250" height="400"/> | <img src="screenshots/shadow_tune3.png" width="250" height="400"/>
| <img src="screenshots/shadow_tune1.png" width="250" height="400"/> | <img src="screenshots/shadow_tune2.png" width="250" height="400"/> | <img src="screenshots/shadow_tune3.png" width="250" height="400"/>

| Script invocation in a Windows 10 VM using Strawberry Perl |
| --- |
| <img src="screenshots/shadowtune4.png"/>

## Limitations
- The script provides no way of accessing and/or modifying individual music tracks, the only available operation
is bulk replacement of everything. This is because even the replacement of only a single track would boil down to
providing a modified `resources.assets.resS` file and performing a standard swap operation. (The number of tracks has to remain
constant otherwise the game will most certainly crash when loading nonexistent music data.)

- *Shadow-Tune* was originally developed in and for a Unix-like environment. Even with version 2.0 its roots are clearly visible
and this decker understands that it is a less than ideal tool for Windows users. Efforts are currently being made to account for
the entrails of a Windows environment but as of now portability is not guaranteed.
- *Shadow-Tune* was originally developed in and for a Unix-like environment. Even with version `2.0` its roots are clearly visible and this decker understands that it is a less than ideal tool for Windows users. Efforts have been made to improve Windows integration and general functionality has been tested with Strawberry Perl.

- Why no GUI I hear you say? The reasons for that are twofold: The design goals for *Shadow-Tune* were simplicity and portability. Upgrading the script from a commandline tool to a full-fledged GUI application would introduce additional dependencies and turn what was originally supposed to be a simple script with one basic purpose into a (by comparison)
heavy runtime behemoth. That being said, a future version with GUI support is not entirely off the table.

## Authors
**Van Ziegelstein** - Creator and Maintainer
Expand All @@ -114,7 +118,7 @@ the entrails of a Windows environment but as of now portability is not guarantee
Every Shadowrunner needs the right team for the job and *Shadow-Tune* wouldn't exist without the groundwork laid by two
particular runners:

**Zetor** - Performed the initial research into the sound resources of Shadowrun Returns and discovered how `resources.assets`
**Zetor** - Performed the initial research into the sound resources of *Shadowrun Returns* and discovered how `resources.assets`
and `resources.assets.resS` were related.

**Cirion** - Creator of the UGC campaigns *Antumbra Saga*, *Caldecott Caper* and *CalFree in Chains*. Expanded Zetor's research
Expand Down

0 comments on commit 7740355

Please sign in to comment.