[DONE] craft preview

[Meridian]

Related threads:
1. craft preview: this thread
2. craft type preview: https://openxcom.org/forum/index.php/topic,10371.0.html
3. base preview: https://openxcom.org/forum/index.php/topic,10372.0.html

This feature allows you to preview and customize the deployment of your units (in a given craft) at the beginning of a battle.

You can start the preview by clicking on the Preview button in the Craft Soldiers GUI.
Presence of a (previously defined) custom deployment is indicated by an asterisk on the 'Preview' button.

If there is at least 1 soldier or 1 HWP onboard, the preview will start.
You have unlimited movement on all your units.
You can also use the Ctrl+W key combo to teleport your units instantly.
Press and hold 'Alt' to highlight valid unit positions.

Click on the 'Abort Mission' icon to save a custom deployment (unit positions + facing).
The game tells you how many units are on valid positions and how many are outside.
Saving is possible only if all units are on valid positions.

Click on the 'End Turn' icon to exit the preview.

Note that adding any new soldiers or vehicles to the craft automatically invalidates the saved custom deployment.
(removing units will not invalidate)
(changing soldier armor from 1x1 to 2x2 also invalidates)
This is a feature, not a bug!
The saved information is bound to this particular craft with these particular units.

Saving is also disabled on craft, which have more than one possible battlescape terrain (since they can be completely incompatible between each other).

If you want to make a more permanent craft deployment changes, you can use the craft type preview feature: https://openxcom.org/forum/index.php/topic,10371.0.html

[Meridian]

More technical info:
- units can freely move (their TU and Energy is fully replenished after each step)
- units cannot be hurt
- the whole map is revealed at start
- save/load are disabled
- autosave/autoload are disabled
- quicksave/quickload are disabled
- forced ironmansave/ironmanload are disabled
- aliens are not spawned
- civilians are not spawned
- reinforcements are turned off
- enviro effects are turned off
- spawning any kind of hostile/neutral units is disabled
- only friendly units, which are spawned from items directly built into the map block can be spawned
- there are no weapons, or any other items
- preview is disabled in New Battle mode
- most script hooks are disabled (so that you can't change the game state by accident), including:

Code: [Select]

NewTurnUnit - SavedBattleGame::newTurnUpdateScripts() completely disabled
NewTurnItem - SavedBattleGame::newTurnUpdateScripts() completely disabled
CreateItem - SavedBattleGame::initItem() completely disabled
CreateUnit - SavedBattleGame::initUnit() completely disabled
ApplySoldierBonuses - SavedBattleGame::initUnit() completely disabled

HitUnit - BattleUnit::damage() completely disabled
DamageUnit - BattleUnit::damage() completely disabled
DamageSpecialUnit - BattleUnit::damage() completely disabled

HealUnit - TileEngine::medikitUse() completely disabled
SkillUseUnit - TileEngine::skillUse() completely disabled
AwardExperience - TileEngine::awardExperience() completely disabled

ReactionCommon - TileEngine::checkReactionFire() completely disabled
ReactionWeaponAction - TileEngine::checkReactionFire() completely disabled
ReactionUnitAction - TileEngine::checkReactionFire() completely disabled

TryPsiAttackItem - no enemies/civilians, no items, player cannot use items
TryPsiAttackUnit - no enemies/civilians, no items, player cannot use items
TryMeleeAttackItem - no enemies/civilians, no items, player cannot use items
TryMeleeAttackUnit - no enemies/civilians, no items, player cannot use items

VisibilityUnit - script will never run, no enemies/civilians

ReturnFromMissionUnit - script will never run, no Debriefing


[Meridian]

Info about the map for preview:
- the map is not hardcoded, you can change it using the STR_CRAFT_DEPLOYMENT_PREVIEW alien deployment definition.
- default deployments use CULTA terrain for xcom1 and SEABED terrain for xcom2
- default map size is 10x10, but will increase automatically if the craft doesn't fit (only width and length can increase, height must be changed manually if needed)
- you can mod also briefing texts, music, etc.
- example I used for testing in 40k mod:

Code: [Select]

alienDeployments:
  - type: STR_CRAFT_DEPLOYMENT_PREVIEW
    music:
      - HANGAR
    briefing:
      title: STR_HANGAR_TITLE
      palette: 4
      desc: STR_HANGAR_DESCRIPTION
      music: HANGAR
      showCraft: true
      showTarget: false
      background: BACK16.SCR
    shade: 1
    terrains:
      - XHANGAR
    script: XHANGAR
    width: 30
    length: 20
    height: 6


You can also have different preview maps for different craft using the `customPreview` attribute:

Code: [Select]

crafts:
  - type: STR_AVENGER
    customPreview: STR_MY_CUSTOM_STUFF     # if not defined, it defaults to STR_CRAFT_DEPLOYMENT_PREVIEW


[Meridian]

Last but not least, the modders can also say whether the player can position the units only within the fixed specified positions (defined by craft's `deployment`) or anywhere on any tile capable of spawning xcom units.

Attribute for this is called `useAllStartTiles`.

Code: [Select]

crafts:
  - type: STR_AVENGER
    useAllStartTiles: true     # default is false


[Finnik]

I tried new release and find a crash case for review of the craft without battlescape map. We could either check if there is a map assigned, but to me, it looks like there is a more simple option to just check for `allowLanding` property. I made a PR that do so - https://github.com/MeridianOXC/OpenXcom/pull/88.  If you don't like it - let me know, but I think such a crash case should be handled anyway.

UPD:
If this solution is valid, I'd also add it for pedia info state, there is the same crash case.

[Meridian]

Yes, I will add a check for battlescape map in the next release.

[Finnik]

And what do you think about `allowLanding` property? I mean, even if it has map, it's kinda meaningless to have a preview for such craft.

[Ethereal]

And what do you think about `allowLanding` property? I mean, even if it has map, it's kinda meaningless to have a preview for such craft.

I think it makes sense. For atmosphere. Anyway, with the available tools, picking up or drawing a map is a matter of an hour. Ie no check for "allowLanding" is needed.

[Finnik]

I think it makes sense. For atmosphere. Anyway, with the available tools, picking up or drawing a map is a matter of an hour. Ie no check for "allowLanding" is needed.

Oh, really? Drawing a fine map for a craft is the matter of an hour?! We either are talking about very different things, or I suck in that COMPLETELY. I meant, I though, that making a brand new detailed map for a new craft (not just making yet another Frankenstein's monster from existing assets, glued together) is the greatest challenge for an artist. I knew very few people in our community, who can make new fine craft maps.
Even with that, it's a pointless work as that craft is not allowed for landing! I mean, it literally can't act in battlescape! Why would it even needs the map? Or a preview for it?

[Ethereal]

Finnik, You can leave out "battlescapeTerrainData" for the ship and it won't have a preview. And if there are maps and a desire, then it is possible for interceptors with "allowLanding: false" to make a preview for atmospheric, as a decorative element. It seems to me that this would be the best solution for everyone.

[Meridian]

And what do you think about `allowLanding` property? I mean, even if it has map, it's kinda meaningless to have a preview for such craft.

Theoretically, you can have a craft that can only land on Mars/finalmission, but not on Earth.

But even if that was not the case, some people (like Ethereal above) might want to be able to see the preview anyway. I don't see a reason why I would not allow him to do that.

Yes, I will add a check for battlescape map in the next release.

The presence of a battlescape map is now checked: https://github.com/MeridianOXC/OpenXcom/commit/6f56ee8049bd869bdfbb2c76226b804d0e695196

[Finnik]

Nice, I just want it to be crash-resistant =)

[Delian]

I have a small critique regarding this feature, and that is, the format in which the data in the savegame is presented is too cryptic / inconsistent with the rest of the savegame data.
This

Code: [Select]

        customSoldierDeployment:
          1:
            -
              - 3
              - 4
              - 0
            - 6
          2:
            -
              - 4
              - 4
              - 0
            - 6
          3:...
should instead be formatted like

Code: [Select]

        customSoldierDeployment:
          - id: 1
            position:
              - 3
              - 4
              - 0
            direction: 6
          - id: 2
            position:
              - 4
              - 4
              - 0
            direction: 6
          - id: 3:...


[Meridian]

I humbly disagree.

Just like (almost) every other object in the save file, this object is also consistently written into the save (and read from the save) in the YAML equivalent of its raw structure (as stored and used in the c++ source code).

To make it look like you want, I would have to do one of two things:
1. change how the object is internally represented... making it hard (and very inconvenient) to use
2. write a custom converter that would transform the object each time it is saved or loaded... which is just a waste of my time (and the CPU time)

[Delian]

The whole point of using YAML is that it's humanly-readable format. Directly storing std::pair<Position, int> objects does not follow this "readability" principle. Also, using YAML at all means any performance implications fly straight out of the window.

>1. change how the object is internally represented...
For a correct raw representation, you'd have to make a new class. Considering this object has very limited usage, I agree that adding a new class would be an overkill.

>2. write a custom converter that would transform the object each time it is saved or loaded...
That's what should've been done, yeah. Craft::load() and Craft::save() would have to include a manual conversion.

Btw, right now this feature is still fresh, so if the format change is made, not many people would lose the deployments they set up.