Import custom books

[TheLacus]

Recently relased alpha build introduces support for custom books, in addition to replacement for classic books which was already available. This feature is still considered experimental but is provided as opt-in to receive early feedback from interested mod creators. For general informations on books modding see modding/books.

This feature has been released and is available for mods to be used. The documentation is available here.

How to enable
Open ini setting file, search [Experimental] section and set

Code: Select all

CustomBooksImport=True

How to import from loose files

1. Place a new book file with .TXT extension inside StreamingAssets/Books. Example: StreamingAssets/Books/ExampleBook.TXT.
2. Create a json file inside StreamingAssets/Books/Mapping. Example: StreamingAssets/Books/Mapping/ExampleBooksPack.json.
   This file must contain an array of objects, one for each book that is to be announced to the game.

   Code: Select all

   [{
      "Name": "ExampleBook.TXT",
      "Title": "An Example Book"
      "ID": 1531909675
   }]
   

   Name is the filename without extension.
   Title is a readable name for the book, shown in game. The reason to have it here is to access it without loading the entire book resource.
   ID An unique ID for the book between 1 and 2147483647 (generate with google).
   IsUnique If true this book is not found inside random loots or bookshelves and must be made available directly by mods.
   WhenVarSet Book is available only when this global variable is set.

How to import from mods
Custom books can be provided from mods (.dfmod) simulating loose files structure. Specifically, place mapping json files inside a directory that ends with Books/Mapping.
For example, you should have something like this:

Code: Select all

<root>/ReadMe.txt
<root>/ExampleMod.dfmod.json
<root>/modsettings.json
<root>/Books/ExampleBook.TXT
<root>/Books/Mapping/ExampleBooksPack.json

What to expect

• Custom books can be read from booshelves.
• Custom books can be found inside random loots and added to inventory as items. If mod provider is removed, books inside inventory become unreadable claiming to be ruined.
• Custom books can be made available by mods

  Code: Select all

  GameManager.Instance.PlayerEntity.Items.AddItem(ItemBuilder.CreateBook("ExampleBook"));
  

[azmanian]

*chronicling the histories of the Illiac's noble families intensifies*

[BansheeXYZ]

I'm interested, except... if you play near 1080p (and most people do), it's kinda hard to read a whole book in what is essentially a size 36 yellow font. 5x scaling only looks good in a twitter thumbnail. So it'd be great to have scaling options for the old ui for enhanced readability. Doom is a 320x200 game as well. Play gzdoom you'll see that not only can choose your own scalings, the default is "adaptive" which makes sure the old HUD/messages doesn't get scaled to 5x just because you bumped the resolution 5x.

[Hazelnut]

I'd like to add a book for the Archaeologists guild with some details and locations of guild halls. When is this feature likely to move from experimental?

[TheLacus]

I'd like to add a book for the Archaeologists guild with some details and locations of guild halls. When is this feature likely to move from experimental?

I want to be cautious and avoid changes to core game before confirmation that there are no regressions. It works fine in my tests so i'm happy to enable this feature for all after someone actually release a book and no bugs are found.

[Hazelnut]

If I put a book into the mod and the books setting is not enabled, will that possibly cause issues? That's my concern I suppose.

[TheLacus]

If I put a book into the mod and the books setting is not enabled, will that possibly cause issues? That's my concern I suppose.

No, it should be fine

[Hazelnut]

Great. Will do this in a couple of weeks when I get back. Should hopefully be a good test case.

[Uncanny_Valley]

Currently this doesn't work.

In DaggerfallWorkshop.Game.Items.ItemBuilder.CreateBook(string fileName), it starts by adding a filename extension to the name, which will result that it wont find the book in BookMappingEntries (where the name is stored without extension).

You do however want to add the file extension in BookReplacement.TryImportBook(string name, BookFile book), probably after the DaggerfallUnity.Settings.AssetInjection check.

After these changes, you can make the book appear in your inventory. using

Code: Select all

"GameManager.Instance.PlayerEntity.Items.AddItem(ItemBuilder.CreateBook("ExampleBook"));" 

But the doesn't get the correct price and it doesn't set the name of the book, it only becomes "Book by unknown Author".

And lastly, if you have a mod that adds a book. It will do so even if the mod is de-activated in the mod loader.

[TheLacus]

Currently this doesn't work.

In DaggerfallWorkshop.Game.Items.ItemBuilder.CreateBook(string fileName), it starts by adding a filename extension to the name, which will result that it wont find the book in BookMappingEntries (where the name is stored without extension).

You do however want to add the file extension in BookReplacement.TryImportBook(string name, BookFile book), probably after the DaggerfallUnity.Settings.AssetInjection check.

After these changes, you can make the book appear in your inventory. using

Code: Select all

"GameManager.Instance.PlayerEntity.Items.AddItem(ItemBuilder.CreateBook("ExampleBook"));" 

But the doesn't get the correct price and it doesn't set the name of the book, it only becomes "Book by unknown Author".

And lastly, if you have a mod that adds a book. It will do so even if the mod is de-activated in the mod loader.

It wasn't needed to provide the extension at first, but i rethinked that because one day we might want to support readable formats like json in addition to format used by classic books, or at least i believe Intekarma suggested that possibility once.
I forgot to update the guide above, sorry for that. If you make a mapping file with this content, custom book is imported automatically and available from bookshelves unless IsUnique flag is set.

Code: Select all

[
    {
        "Name": "ExampleBook.TXT",
        "Title": "An Example Book",
        "ID": 1531909675
    }
]