Whenever the a vehicle is loaded/unloaded from a vehicle wagon, the train forgets half of its configuration which leads to problems like it not going to refuel when necessary and running out of juice halfway across the desert. Not much else, that's the bug and how to reproduce it.

Thanks for the report. This doesn't surprise me, since currently the Factorio API does not allow reading or writing schedule interrupts at all, and writing to just the schedule will erase all the interrupts.

Try adding the train to a named group. This can allow the interrupts to be restored from the group in some situations.

If the train is the only member of its group, then the group gets deleted and the interrupts are lost. It does work and restore interrupts correctly if there's another train in the group, but I only need one personal transport train and would rather not have a locomotive sat out doing nothing just for this purpose.

Perhaps there's a way around that, saving the train group in storage, or nastiest workaround imaginable, having a locomotive for each train group on a hidden internal surface just to make sure it doesn't get lost?

There is another, closely related problem.

If it copies from a train group, it keeps interrupts, but any temporary stops currently in the schedule are lost. Loading a vehincle at a temporary stop causes it to depart immediately.

Very good points. I will test it to see if any simple changes can improve this. It may be that my schedule-restoring logic is simply unnecessary for vehicle wagons and it causing these problems.

I tested what would happen if my mod does not attempt to write the schedule or group when it changes the loaded for an unloaded wagon (or vice versa). When I have it load at an interrupt stop, the temporary record for the interrupt stop stays in the schedule, but when the train is reassembled and set back to automatic, it starts at the beginning of the schedule anyways.

Currently, the script writes the schedule if there is one (including temporary stops and which record is next, and erases interrupts), then writes the group if there is one (which erases the temporary stops in the schedule and resets to the first record, and adds interrupt definitions), and then sets the train to automatic mode.

If I don't set the group, then the schedule gets set and the train stays at the temporary stop but no longer has any interrupts defined. If I don't set the schedule, but do set the group, then it's just like it is now. If I set neither, then the train retains the temporary stop and the group but still departs to the first schedule entry, without removing the temporary stop it just left.

There is no winning with the current broken state of the API, sorry.

What would be the ideal API for this mod? Maybe something like the ability to swap out train cars or change train car state of a stopped train?

All we need is any way at all to read and write interrupts to a train or group. Many other mods are rendered useless by this gap as well (like Automatic Coupling System).

But if you want to make something specifically for this mod, it would be a way to change the sprite set of an entity without having to delete it and create a whole new entity. I don't think that's likely to be implemented.

I see, thank you for explaining.