Author: RobP

I have decided to temporarily put down the calendar Mk2 work to get out some fixes and enhancements out to you good folk. This is exactly what I did last year before Christmas for custom folders.

The idea is that once this release is out I will be going back to calendar system.

The reason the calendar system is taking so long is due to its flexibility. This leads to an inordinate number of corner cases each of which have to be tested. It’s amazing how many of them are exhibiting issues. The calendar work is headed the right way, but it’s going to take time!

Version 1.4 primarily focuses on how Sojour saves your data, though there are other enhancements that will be discussed below.

Why a new save mechanism?

It’s because over Sojour’s two years of public releases I have had 3 or 4 reports of users losing data due to the main Sojour.dat file being corrupted. This seems to happen when a network drive goes away during a save, or when Sojour itself crashes – which can happen during large image imports due to limitations with the Windows GDI.

To that end I decided to completely revamp the save system in order to prevent the core Sojour files ever being corrupted.

Sojour has moved away from an opaque system of saving frequently in the background, to one where the user has to explicitly choose to save their data – though there are exceptions to this.

To achieve this, Sojour got a brand new Save button on the main toolbar:

This save button saves almost everything, except PDF’s. This is a limitation of the free PDF component that Sojour uses. To save the PDF’s you have to use the save button directly on the PDFs themselves. (I’m looking at replacing this component with a more expensive commercial one, but that is a future endeavour)

Hovering over the new save button displays how long it was since your last save. We can see that this was 2 minutes ago in the above image.

If you change anything significantly within Sojour, the save button will change to let you know:

It might seem a backward step to remove the continuous background saving, but there are two main reasons for this:

1. Transparency – The user now knows when their work is saved because they are having to explicitly do it themselves. This should lead to a greater peace of mind as the user will know that their work has been saved.
2. Speed – The new save system now performs data verification, this makes the saves take a little longer, thus making them unsuitable for use in a continuously saved model – trust me, it would annoy you!

The loading and saving now takes long enough that you will see a window telling you what’s going on:

Sojour has similar windows for loading and updating.

Although the system is now primarily a manual one, there are some occasions where Sojour will automatically save your data. These are:

1. Closing Sojour
2. Just prior to a map import – either by file or screenshot
3. As part of the user defined automatic saves.

Closing Sojour is an obvious use case, the other two items below it will need further explanation.

First up the map import.

Sojour initially imports all images using the Windows GDI’s Image class. I think it would be fair to say that this class is somewhat flaky when it comes to large images and it does occasionally crash. Sometimes, the crashes are so severe that they can take down Sojour (even with protective code to prevent this).

Performing full saves prior to the map imports mean that in the event of anything going wrong, you do not lose your data.

As for the latter item – automatic saves – they have always been in Sojour, but they are now a little more in-your-face as they display a window when the saves are happening.

By default, Sojour is set to automatically save every hour, but you can change this, or even disable it if you want to:

What makes the new system safer?

Simples, it’s the way it saves the three most important files within Sojour: Sojour.dat, AssetTreeView.dat and AppStatus.dat.

The first thing that Sojour does is to create duplicate versions of the files it is about to save. These duplicates are pre-pended with ‘PREVIOUS_VERSION_’. These can be seen below:

The next thing that happens, is that Sojour will then save its data into a temporary file which will be prepended with the words ‘VERIFICATION_TEST_’.

This is a file that the user will never normally see – unless something goes wrong.

Saving to a temporary file rather than directly to the original offers us the opportunity to verify its contents prior to overwriting the original file.

The screenshot below shows a paused Sojour within the debugger so that you can see this temporary file:

Sojour then verifies that file’s integrity by loading it in the background. If this verification step succeeds, the verification version of the file is copied over the original file – in this example it would be Sojour.Dat.

This system has several advantages over the old system:

1. Sojour’s critical files are never overwritten directly until the data has been verified to work. This means that if Sojour crashes or a network drive goes away during a save, this is not an issue. The only file that can be potentially corrupted is the verification one. The files that Sojour actually uses will be intact.
2. If the final copy from a verification file to an original file fails, that is still not an issue for Sojour. It has already made a backup of that file called ‘PREVIOUS_VERSION’ and Sojour can then automatically opt to use that one in the event that the original file has some how been corrupted (this should be nearly impossible due to item 1 above).

This is a much more ‘enterprise’ level system than the original and one that I could not break, even under some rather arduous conditions.

That’s the new file system mechanism. What else got added?

First up is a new NPC bar for the journals:

The new bar is much larger than the original and now incorporates a scroll bar that will automatically appear and disappear as needed. This means that you can add as many NPC’s to your map, without the NPC bar cutting them off.

Waving your mouse cursor over an NPC on the map will scroll the NPC bar to bring the relevant NPC into view whereupon it is temporarily highlighted in light blue. The same also happens in reverse too.

This should make it much easier to associate NPC map tokens with their toolbar counterparts and vice-versa.

Another change added to Sojour is a new ‘Dice Roll’ field for lookup tables.

This field allows a user to enter external dice results, rather than have Sojour roll the dice:

A typical use case for this field is for when the user wants to roll physical dice on one of Sojour’s tables. Simply pick a table, roll your physical dice, then enter your dice result into that field along with modifiers. This will activate the chosen table with he results of your physical dice!

As an aside, the reason for the new UI colours is to enable users to easily associate the tables drop down list with the dice roll field – as one directly affects the other.

Another enhancement added to Sojour’s tables is the ability to insert dice expressions into your table results:

When this table is run a few times you could get results similar to this:

Thanks to the dice expressions, we how have a variable number of creatures that can turn up for each table row!

The tables support all four dice expression formats that the journals do (it’s the same code) and you can make those expressions as simple or as complex as you like.

Before we finish with tables and dice expressions, there is one more thing that you can do with them and it is exceptionally powerful!

You can now use dice expressions with table name redirects:

For the above screenshot, if the system (or user) rolls a 7 on the Encounters table, Sojour will then roll a 1d2 dice (an impossible dice in real life, but one that Sojour can roll). The result of this 1d2 dice determines which Advanced Encounters table the Encounters table will refer to.

For example, if it rolls a ‘1’, it will refer to the ‘Advanced Encounters 1’ table and if it rolls a ‘2’ it will refer to the ‘Advanced Encounters 2’ table.

This is a very powerful mechanism that allows you can go completely nuts and link as many tables together as you want! 🙂

Another new feature that got added is a ‘Find Prev’ button to the Journal Find window:

This should make finding things in your journals a lot easier!

The new table’s features and the find enhancement were both customer requested enhancements. If you have any ideas, send me an email using the address at the front of the manual and I’ll see what can be done!

Another thing that got upgraded is the image import function.

As noted earlier, the Windows GDI is somewhat flaky, especially with bigger images.

To get around this, Sojour now compresses all images imported into it via file or screenshot.

The compression setting can be set using a new setting within the Settings dialog called Graphic Import Quality:

Image compression makes a huge difference to memory usage.

For example, here is a large map imported with the previous version of Sojour:

38.2Mbs! That is a large image file.

Here is the same file imported with this new version of Sojour:

Note the difference in size.

The newly imported map is 1.52mb vs the 38.2mb of the original import. That’s quite a saving – around 25 times smaller for no appreciable loss of quality!

This vast reduction in image size should make Sojour a lot more stable when importing large images.

A full list of changes and fixes will be produced nearer the time of release.

I guess the next question is: ‘When can I get this version?’

The answer is in around 1 or 2 weeks time, assuming a fair wind.

The coding is done, but that leaves the large manual and all its screenshots to update – this is why the release is getting delayed. On the plus side, it gives me more time to exercise the new functions.

Also, for those that don’t know, all Sojour enhancements are free for paying customers!

That’s it for this post!

Have fun!

RobP