-
Notifications
You must be signed in to change notification settings - Fork 100
Implementation Concepts Important Notes for Developers
On this page, we want to document some important implementation concepts relevant to the game development. Please keep in mind that this is by far not a complete list but rather should grow over time.
For JSettlers, building configurations are defined in xml files in jsettlers.common/src/main/resources/jsettlers/common/buildings. The files define:
- blocked and protected positions
- location and type of the building flag
- location of the construction posts (buildmarks)
- bricklayer positions during construction
- image indexes
- allowed ground types
- worker type (if a worker is required)
- offer and request stacks
- the job of a worker (if a worker is working in this building)
A building has blocked and protected positions. Blocked positions are blocked for movables, meaning they cannot walk on these locations when the building construction by the bricklayers has begun. All positions covered by the building image should be marked as blocked so movables don't walk through buildings.
Protected positions can be walked on by pathing movables. However, if a movable has nothing to do, it will try to get away from protected positions to keep these areas free of movables. Furthermore, buildings and trees cannot be placed on protected positions, making sure that a protected position is always walkable.
Important: All buildings must have a full border of protected positions around their blocked positions. Furthermore all positions with a stack (over or request) of a building and all locations walked by a building worker must be marked protected. This ensures several aspects:
- The protected positions will always be walkable => the building worker will always be able to do his job
- Two buildings will always have two walkable positions in between them and there is always at least one walkable position between a building and the border or any other non-walkable obstacles. This ensures movables can always reach all non-blocked positions on the same "continent".
There are three types of stacks:
- Construction stacks: are used to define the materials needed to construct a building. Furthermore, they define the location where the materials should be delivered to.
- Request stacks: are used to define where goods should be transported to and which goods are needed at that location (request stacks)
- Offer stacks: must be placed at the location where the building worker drops the produced materials. These locations are solely used to check the available amount of materials to display that number in the UI.
Important: All stacks of buildings must be on a protected position of that building. This is required to ensure that the position is allways reachable (no tree or other building can be placed on top of it). Naturally, all stacks must be on non-blocked positions of the building.
The AutoReplayIT is an integration test for the complete game logic. It simply uses a recorded game to simply replay it and create several savegames and fixed time steps. These savegames are then compared with reference files in the repository.
This test is especially important for refactorings or non-game-logic-related works. In both cases, the test should not fail and thus indicate that the game behavior did not change.
Unfortunately, due to our current save system (using Java object serialization), the savegames are highly sensitive to changes in the fields of persisted objects. Therefore, if you rename some fields, it is expected to change the savegame and therefore break the test. It is best to encapsulate such changes in single commits where you can be sure to not have changed something in the game logic.
To get the AutoReplaIT working again after you've intentionally changed something causing it to fail, you have to regenerate the reference files. This can be done by simply running the main method of jsettlers.integration.replay.RegenerateAutoReplayITReferences. Afterwards, you have to commit the updated reference files.
Please also keep in mind that when you develop a new feature for the game logic, it might be neccessary to create a new replay file which includes using the new feature. When this is done, it is important that the current reference tries to include all game features. If it is replaced, the same as to be achieved by using all features in the played game. Changes to features that aren't used in the reference might not be detected by the AutoReplayIT undermining its key idea.