Difference between revisions of "HPL2/TDD/Creating a Custom Story"

From Frictional Wiki
< HPL2‎ | TDD
Jump to navigation Jump to search
(→‎Wrapping up your Custom Story: Made smth more understandable)
m
(7 intermediate revisions by the same user not shown)
Line 1: Line 1:
{{note|The simplest way of starting a Custom Story is downloading a [https://www.mediafire.com/file/m0yw9ro94yruzk6/Custom_Story.zip/file template]. The following tutorial will help with understanding what those files do.}}
+
{{TocRight}}
 +
Creating a working custom story is a relatively simple process. This page will explain what you need to set up to do so, but it will not go into how you create engaging content as that is a much more invested topic.
  
{{todo|Reupload the template to the wiki}}
+
To get started, browse to your Amnesia TDD installation directory. This is often called the ''Amnesia root directory'', and where it is located depends on the system and platform you are using. Here are some common locations:
 +
{| class="wikitable"
 +
|Steam @ Windows
 +
|<code>C:\Program Files (x86)\Steam\steamapps\common\Amnesia The Dark Descent</code>
 +
|-
 +
|Retail @ Windows
 +
|<code>C:\Program Files (x86)\Amnesia</code>
 +
|-
 +
|Steam @ Mac
 +
|<code>~/Library/Application Support/Steam/steamapps/common/Amnesia The Dark Descent</code>
 +
|}
  
= Wrapping up your Custom Story =
+
==Setting up a custom story==
 +
{{note|The simplest way of starting a Custom Story is downloading a [https://www.mediafire.com/file/m0yw9ro94yruzk6/Custom_Story.zip/file template]. The following tutorial will help with understanding what those files do.}}{{todo|Reupload the template to the wiki}}
  
<s>This list assumes that you already went through all the level design, special entity creation, level building and scripting, and that you want to fix your custom story so it shows in the Custom Story launcher.</s>
+
Depending on your version, you may have a folder called "redist" inside your root directory. If you do, you will be working from inside this folder. If you do not have the "redist" folder, you will be working from the root directory itself.
  
{{todo|The above is misguiding and should probably be deleted.}}
+
#Navigate to <code>custom_stories/</code>
 
+
#Create a new folder for your custom story. This folder can be named pretty much anything, for example "My First Story".
# Create a subfolder (story root from now on) for the story under <code>redist/custom_stories</code>. Name it anything you please. '''Keep in mind that changing this folder's name might break certain things in maps made when the folder had the previous name.'''
+
#Enter your new folder and create a new plain text file named <code>custom_story_settings.cfg</code>. Open this file in your favorite code editor and paste in the following XML configuration:<syntaxhighlight lang="xml">
# Copy your maps, scripts, and anything you created for the custom story into the story root. You may want to organize all stuff in subfolders. Maps with corresponding scripts, by default, should be located in a subfolder called 'maps'.
 
# Create a text file named 'custom_story_settings.cfg' in the story root. The contents of this file should look like this: <syntaxhighlight lang="xml">
 
 
<Main
 
<Main
Name="A cannon story"
+
Name="My First Story"
Author="Luis Rodero"
+
Author="Lovecraft Himself"
ImgFile="cannonbg.jpg"
+
ImgFile="cool_bg.png"
 
 
StartMap="luis_script_test.map"
+
MapsFolder="maps/"
StartPos=""
+
StartMap="level_01.map"
 +
StartPos="PlayerStartArea_1"
 +
 
 +
ExtraLangFilePrefix="extra_"
 +
DefaultExtraLangFile="english.lang"
 
/>
 
/>
</syntaxhighlight>
+
</syntaxhighlight>You can change any fields you like, for instance the name and author, but you may want to come back to this later. See the link at the bottom for a full explanation of this file. [[File:Custom story empty example.png|alt=A bare minimum custom story configuration|thumb|A bare minimum custom story configuration]]
#*''' Name:''' Name of the custom story. 'Unnamed Story' will be shown if empty.
+
#The next requirement before the story will appear in the game's menu is a valid map file. Open the level editor and create a simple room – or at the very least create a floor using the Plane tool, place down a Box Light to cover the area, and place a PlayerStart area. Save the map file into <code>custom_stories/My First Story/maps/level_01.map</code>, or whatever matches the setup you've used. Don't forget to create the "maps" folder as it is written in your config file.
#*''' Author:''' Name of the author. 'Anonymous' will be shown if empty.
+
#At this point, if you launch Amnesia, your story should appear in the list of custom stories as seen in the image to the right. Feel free to test this to ensure everything works so far. If you click "Start" you should load into your level.
#*''' ImgFile:''' Image file that will be used as background in the Custom Story Launcher. This is optional.
+
#Optional: Add the image file as specified by the <code>ImgFile</code>attribute above. Match the name and extension and place the file next to your config, and it should render as the background image in the game menu.
#*''' StartMap''': File name of the map that will be started when the custom story is launched. This value cannot be empty.
+
 
#*''' StartPos:''' Name for the position in the start map where the player will be spawned. If empty, the first one defined will be used.
+
==Displaying text==
# All custom messages, diaries and notes that your custom story needs in a 'extra_english.lang' file in the story root. If translations want to be made, these are to be created as 'extra_' + name_of_the_supported_language + '.lang' files, with name_of_the_supported_language being one of the ones that you can choose in the game options menu. Optionally, this can contain an entry "Description" in the "CustomStoryMain" category, and any brief description on the custom story can be written here. It will be displayed in the Custom Story Launcher. Just to display an example: <syntaxhighlight lang="xml">
+
Now that you have a functional custom story, it's time to add some other essential files. In the image to the right you may notice it says "No description." This is the fallback text that appears if you do not have a functional language file, so let's create that now.
<CATEGORY Name="CustomStoryMain">
+
 
    <Entry Name="Description">Just a brief description!</Entry>
+
#Start by creating a new plain text file in your custom story folder named <code>extra_english.lang</code>.
</CATEGORY>
+
#Open the language file. This is another XML file that stores ALL text that will be displayed in your story. This includes things like descriptions, pop-up text, notes, item names, level names etc.  You can start by pasting in the following:<syntaxhighlight lang="xml">
</syntaxhighlight>
 
# You must use the EXACT tags as shown for CATEGORY. Also, the CATEGORY tag must be inside the required LANGUAGE tag in the 'extra_english.lang' file. So, if you have nothing else other than the description, it should look like the following (take special note of upper-case vs. lower-case - it must be EXACTLY like this) <syntaxhighlight lang="xml">
 
 
<LANGUAGE>
 
<LANGUAGE>
  <CATEGORY Name="CustomStoryMain">
+
<CATEGORY Name="CustomStoryMain">
      <Entry Name="Description">
+
<Entry Name="Description">Hello, this is the description of my story.</Entry>
        Just a brief description!
+
</CATEGORY>
      </Entry>
 
  </CATEGORY>
 
 
</LANGUAGE>
 
</LANGUAGE>
</syntaxhighlight>
+
</syntaxhighlight>There are a few rules to keep in mind when it comes to this file:
# If you do not capitalize EXACTLY as shown, it WILL NOT work. If you don't have the enclosing LANGUAGE tag, it WILL NOT work. Only one LANGUAGE tag should be in the 'extra_english.lang' file. All 'CATEGORY' tags should be inside that.
+
##All text within this file is CASE SENSITIVE, meaning if you write "language" instead of "LANGUAGE" it will not work.
 +
##The file MUST start with the opening <code><LANGUAGE></code> tag and it MUST end with the closing <code></LANGUAGE></code> tag. This element should only occur once in the entire file.
 +
##Inside the LANGUAGE element,  you can place as many CATEGORY elements as you wish, but ensure that every opening tag is always accompanied by a closing tag.
 +
##Certain CATEGORY tags require a specific value in the "Name" attribute. For instance, the main menu description is required to be within a category named <code>CustomStoryMain</code>.
 +
##You can place as many Entry elements as you wish inside each CATEGORY element. The actual text that appears in the game will be written between the opening and closing tag for the Entry. Similarly to CATEGORY tags, certain Entry tags require specific values in their name attribute for the game to pick it up. In the above example, the description must have the name <code>Description</code>.
 +
##If any errors are encountered while the game parses this file, the entire file will fail to load and no custom text will appear in your story. You will know that it failed to load if you see "No description" in the game menu.
 +
 
 +
==Moving on==
 +
You have now set up the basic configuration for a custom story. What's left to do now is to create your levels using the level editor, create scripts for your levels using any code editor, and optionally add extra assets you wish to use to additional folders inside your custom story directory. These topics are very expansive and are not covered here, but you can follow the links below for more information on them.
  
Once all this is done, you should be ready to go! The example used should look like this:
+
Your final results from following this guide should leave you with a custom story folder that has this structure:<pre>
 +
My First Story/
 +
|- maps/
 +
|  |- level_01.map
 +
|
 +
|- cool_bg.png
 +
|- custom_story_settings.cfg
 +
|- extra_english.lang</pre>
  
<gallery mode="nolines" widths="320" heights="320">
+
==See also==
File:customstorylauncher01.jpg|On the Custom Story List window
 
File:customstorylauncher02.jpg|After selecting a Custom Story
 
</gallery>
 
  
To ease installation for others, you may now archive the full story root directory, stored from the custom_stories folder.
+
*[[HPL2/custom story settings.cfg|Explanation of the custom_story_settings.cfg file]]
The archive directory tree from the example should look like this (assuming the story root is called TheCannonMap):
+
*[[HPL2/Tools/Level Editor|How to navigate the Level Editor]]
<pre>
+
*[[HPL2/Tutorials/Level Design|Using the level editor to design maps]]
  TheCannonMap/
+
*[[HPL2/ScriptReference|Introduction to AngelScript and level scripting]]
  |- maps/
 
  | |- luis_script_test.hps
 
  |  |- luis_script_test.map
 
  |
 
  |- cannonbg.jpg
 
  |- custom_story_settings.cfg
 
  |- extra_english.lang
 
</pre>
 

Revision as of 20:46, 16 September 2020

Creating a working custom story is a relatively simple process. This page will explain what you need to set up to do so, but it will not go into how you create engaging content as that is a much more invested topic.

To get started, browse to your Amnesia TDD installation directory. This is often called the Amnesia root directory, and where it is located depends on the system and platform you are using. Here are some common locations:

Steam @ Windows C:\Program Files (x86)\Steam\steamapps\common\Amnesia The Dark Descent
Retail @ Windows C:\Program Files (x86)\Amnesia
Steam @ Mac ~/Library/Application Support/Steam/steamapps/common/Amnesia The Dark Descent

Setting up a custom story

Note icon.png The simplest way of starting a Custom Story is downloading a template. The following tutorial will help with understanding what those files do.

To do: Reupload the template to the wiki

Depending on your version, you may have a folder called "redist" inside your root directory. If you do, you will be working from inside this folder. If you do not have the "redist" folder, you will be working from the root directory itself.

  1. Navigate to custom_stories/
  2. Create a new folder for your custom story. This folder can be named pretty much anything, for example "My First Story".
  3. Enter your new folder and create a new plain text file named custom_story_settings.cfg. Open this file in your favorite code editor and paste in the following XML configuration:
    <Main
    	Name="My First Story"
    	Author="Lovecraft Himself"
    	ImgFile="cool_bg.png"
    	
    	MapsFolder="maps/"
    	StartMap="level_01.map"
    	StartPos="PlayerStartArea_1"
    
    	ExtraLangFilePrefix="extra_"
    	DefaultExtraLangFile="english.lang"
    />
    
    You can change any fields you like, for instance the name and author, but you may want to come back to this later. See the link at the bottom for a full explanation of this file.
    A bare minimum custom story configuration
    A bare minimum custom story configuration
  4. The next requirement before the story will appear in the game's menu is a valid map file. Open the level editor and create a simple room – or at the very least create a floor using the Plane tool, place down a Box Light to cover the area, and place a PlayerStart area. Save the map file into custom_stories/My First Story/maps/level_01.map, or whatever matches the setup you've used. Don't forget to create the "maps" folder as it is written in your config file.
  5. At this point, if you launch Amnesia, your story should appear in the list of custom stories as seen in the image to the right. Feel free to test this to ensure everything works so far. If you click "Start" you should load into your level.
  6. Optional: Add the image file as specified by the ImgFileattribute above. Match the name and extension and place the file next to your config, and it should render as the background image in the game menu.

Displaying text

Now that you have a functional custom story, it's time to add some other essential files. In the image to the right you may notice it says "No description." This is the fallback text that appears if you do not have a functional language file, so let's create that now.

  1. Start by creating a new plain text file in your custom story folder named extra_english.lang.
  2. Open the language file. This is another XML file that stores ALL text that will be displayed in your story. This includes things like descriptions, pop-up text, notes, item names, level names etc. You can start by pasting in the following:
    <LANGUAGE>
    	<CATEGORY Name="CustomStoryMain">
    		<Entry Name="Description">Hello, this is the description of my story.</Entry>
    	</CATEGORY>
    </LANGUAGE>
    
    There are a few rules to keep in mind when it comes to this file:
    1. All text within this file is CASE SENSITIVE, meaning if you write "language" instead of "LANGUAGE" it will not work.
    2. The file MUST start with the opening <LANGUAGE> tag and it MUST end with the closing </LANGUAGE> tag. This element should only occur once in the entire file.
    3. Inside the LANGUAGE element, you can place as many CATEGORY elements as you wish, but ensure that every opening tag is always accompanied by a closing tag.
    4. Certain CATEGORY tags require a specific value in the "Name" attribute. For instance, the main menu description is required to be within a category named CustomStoryMain.
    5. You can place as many Entry elements as you wish inside each CATEGORY element. The actual text that appears in the game will be written between the opening and closing tag for the Entry. Similarly to CATEGORY tags, certain Entry tags require specific values in their name attribute for the game to pick it up. In the above example, the description must have the name Description.
    6. If any errors are encountered while the game parses this file, the entire file will fail to load and no custom text will appear in your story. You will know that it failed to load if you see "No description" in the game menu.

Moving on

You have now set up the basic configuration for a custom story. What's left to do now is to create your levels using the level editor, create scripts for your levels using any code editor, and optionally add extra assets you wish to use to additional folders inside your custom story directory. These topics are very expansive and are not covered here, but you can follow the links below for more information on them.

Your final results from following this guide should leave you with a custom story folder that has this structure:

 My First Story/
 |- maps/
 |  |- level_01.map
 |
 |- cool_bg.png
 |- custom_story_settings.cfg
 |- extra_english.lang

See also