User Manual for IFLE Engine v0.1

Welcome to the Interactive Fiction Engine (IFLE) v0.1! This little engine written by Nikos Fakos (astric-games.itch.io).This manual will guide you through the features, commands, file structures, and logic of the engine. The engine is designed to create and play text-based adventure games, where players can explore rooms, interact with items, and solve puzzles.

1. Getting Started

1.1. Running the Game

To start the game, ensure you have the following files in the same directory as the compiled Java code:

• rooms.txt (contains room data)
• Items.txt (contains item data)
• progress.txt (saves player progress)
• rooms.bu (backup of rooms.txt)
• Items.bu (backup of Items.txt)

Run the GameGUI class. A window will open where you can interact with the game.

2. Game Commands

The game supports the following commands:

2.1. Movement Commands

• look: Re-displays the current room's description, items, and exits.
• <direction>: Move to a connected room. Replace <direction> with a valid exit (e.g., north, south, east, west).

2.2. Item Commands

• get <item>: Pick up an item from the current room.
  • Example: get key
• drop <item>: Drop an item from your inventory into the current room.
  • Example: drop key
• inventory: Display the items in your inventory.
• examine <item>: Get the description of an item in your inventory or the room.
  • Example: examine key
• use <item>: Use an item from your inventory.
  • Example: use key

2.3. Game Management Commands

• save: Save your current progress (room and inventory) to progress.txt.
• reset: Reset the game to its initial state. This restores rooms.txt and Items.txt from their backups (rooms.bu and Items.bu).
• quit: Exit the game.

3. File Structure

3.1. rooms.txt

This file defines the rooms in the game. Each room has the following structure:

Room Title Room Description [Action Room:description:A newly renovated action room],[Action Room:items:Magic Scroll] Item1, Item2, @HiddenItem Exit1, Exit2, @HiddenExit

• Room Title: The name of the room.
• Room Description: A description of the room.
• Actions: A list of actions that modify other rooms or items. Actions are enclosed in square brackets [] and separated by commas.
  • Example: [Action Room:description:A newly renovated action room]
• Items: A comma-separated list of items in the room. Items prefixed with @ are hidden (e.g., @HiddenItem).
• Exits: A comma-separated list of exits. Exits prefixed with @ are hidden (e.g., @HiddenExit).

Action Syntax

Actions are written in the format [TargetRoom:FieldName:NewValue]:

• TargetRoom: The room to modify.
• FieldName: The field to modify (description, items, exits, name, or actions).
• NewValue: The new value for the field.

Example:

• [Action Room:description:A newly renovated action room]: Updates the description of Action Room.
• [Action Room:items:Magic Scroll]: Adds Magic Scroll to Action Room's item list.
• [Action Room:items-reset:Magic Scroll]: Clears Action Room's item list and sets it to only contain Magic Scroll.

3.2. Items.txt

This file defines the items in the game. Each item has the following structure:

Item Name Item Description Item Action Record Item Use Message

• Item Name: The name of the item.
• Item Description: A description of the item.
• Item Action Record: An action that occurs when the item is used. This can be null if no action is required.
• Item Use Message: A message displayed when the item is used.

Example: Key A rusty old key. [Room 2:exits:Secret Door] You unlock the door with the key.

3.3. progress.txt

This file saves the player's progress. It contains:

Current Room: Room Title Inventory: Item1 Item2

• Current Room: The room the player was last in.
• Inventory: A list of items in the player's inventory.

3.4. Backup Files

• rooms.bu: A backup of rooms.txt. Used to restore the game to its initial state.
• Items.bu: A backup of Items.txt. Used to restore the game to its initial state.

4. Game Logic

4.1. Hidden Items and Exits

• Items and exits prefixed with @ are hidden.
  • Example: @HiddenItem, @HiddenExit
• Hidden items can be picked up, dropped, and used like normal items.
• When a hidden item is dropped, it loses the @ prefix and becomes visible.

4.2. Actions

Actions are used to modify rooms or items dynamically. They are written in the format [TargetRoom:FieldName:NewValue]:

• FieldName:
  • description: Updates the room's description.
  • items: Adds an item to the room.
  • items-reset: Clears the room's item list and sets it to the new value.
  • exits: Adds an exit to the room.
  • name: Changes the room's title.
  • actions: Adds an action to the room.

Example:

• [Room 2:items:Ancient Map]: Adds Ancient Map to Room 2's item list.
• [Room 2:items-reset:Ancient Map]: Clears Room 2's item list and sets it to only contain Ancient Map.

4.3. Nested Actions

Actions can be nested within other actions. For example:

[Room 2:actions:[Room 2:items:Ancient Map]]

This adds an action to Room 2 that, when triggered, adds Ancient Map to Room 2's item list.

5. Example Game Setup

5.1. rooms.txt

Starting Room This is the first room. [Action Room:description:A newly renovated action room],[Action Room:items:Magic Scroll] ITEM A Room 2 Room 2 This is a brand new description with ITEM B [[Room 2:items:Ancient Map]] ITEM X, ITEM B Starting Room

5.2. Items.txt

Key A rusty old key. [Room 2:exits:Secret Door] You unlock the door with the key. Magic Scroll A scroll with ancient writings. null You read the scroll, but nothing happens.

6. Troubleshooting

• Error: Room not found: Ensure the room title in rooms.txt matches the title used in actions or exits.
• Error: Invalid action format: Ensure actions are written in the format [TargetRoom:FieldName:NewValue].
• Error: File not found: Ensure rooms.txt, Items.txt, progress.txt, rooms.bu, and Items.bu are in the correct directory.

7. Conclusion

The IFLE Engine v0.1 is a flexible and powerful tool for creating text-based adventure games. Consider some combinations with the features. Many ways with many possibilities! I'm looking forward to publish a game built with this engine. So, stay tunned! By following this manual, you can design intricate worlds, create dynamic interactions, and provide players with an immersive experience. Remember, its the first version, expect some errors. Enjoy building your game!