This version of the DIS plugin is deprecated and will no longer be receiving updates. Please refer to the Unreal Engine 5 version.

Getting Started

• This plugin was made for Unreal Engine 4.27
• Clone this repository
• Put the unpacked plugin folder in the 'Plugins' folder for the desired project.
  • The plugins folder should be located in the root directory of the project. If not, create one.
• Launch the project and allow Unreal to rebuild needed modules.
• The GRILL DIS for Unreal plugin should be enabled upon the project opening.

Required Actors

• Certain actors are required to be in a given level in order for the plugin to work as desired. These are listed below:
  • NOTE: Only one of each unique actor type listed below should be in a single level.

• The GeoReferencingSystem actor is required in a level and can be found from the GeoReference Plugin by Epic Games. This plugin should be included when the GRILL DIS for Unreal plugin is installed and it should be enabled by default.
  • This actor stores the Origin Location in real world coordinates in either LLA or in Projected CRS. This is used for conversions between real world coordinated and Unreal Engine coordinates.
    • The website http://epsg.io/ can be used for getting Projected CRS locations.
    • More information on the actor itself can be retrieved at Unreal Engine's Georeferencing Documentation

• The DIS Game Manager actor is also required in the level and is built into the GRILL DIS for Unreal plugin.
  • This actor stores the DIS Enumeration to class mappings and other various DIS information.
  • More information on the actor itself can be found in the DIS Game Manager section below

Implemented DIS PDUs

The GRILL DIS for Unreal plugin currently supports the below PDUs:

• Entity State
• Entity State Update
• Remove Entity
• Fire
• Detonate
• Start Resume
• Stop Freeze

If additional PDU support is desired a few steps need to be taken:

1. Make a new Unreal Engine C++ class to contain the PDU information
   • This class will act as a container for the OpenDIS library version of the PDU. It will allow for interoperability between the PDUs and Unreal Engine.
2. In the PDU Processor class, add in a new case into the "ProcessDISPacket" function for processing the new PDU type.
3. In the DIS Game Manager class, add in a new function for handling logic the received PDU needs to perform.

Setting Up an Empty Project

If creating a new project using the GRILL DIS for Unreal plugin, the following steps can be performed to set it up with DIS capabilities. Additional info for all of these topics can be found in their respective sections below.

Receiving DIS

1. Place a single DIS Game Manager actor into the level
   • This actor can be searched for via the "Place Actors" window in Unreal Engine.
2. On the DIS Game Manager, alter the network parameters according to the needs for the project.
   • The network parameters are located on the DIS Game Manager inside of the Networking header under the GRILL DIS tab.
   • The receive sockets are utilized to handle incoming DIS network packets.
3. Place a single Geo Referencing System actor into the level
   • This actor can be searched for via the "Place Actors" window in Unreal Engine.
4. On the Geo Referencing System, set the "Origin Location" variable to the geospatial location that the Unreal Engine origin is desired to be at.
5. Make custom Unreal Engine actors for all DIS entities the project is expected to receive and handle.
   • Attach a DIS Receive Component to all of the actors that are going to be DIS entities and set the parameters on the component accordingly.
     • This component contains events for handling incoming DIS information.
6. Create a custom DIS Enumeration Mapping asset that maps DIS entity types to the custom Unreal Engine actors made in step 5.
7. On the DIS Game Manager, set the "DIS Enumeration Mapping" variable on it to the DIS Enumeration Mapping asset made in step 6.

Sending DIS

1. Place a single DIS Game Manager actor into the level
2. On the DIS Game Manager, alter the network parameters according to the needs for the project.
   • The network parameters are located on the DIS Game Manager inside of the Networking header under the GRILL DIS tab.
   • The send sockets are utilized to emit DIS network packets.
3. Place a single Geo Referencing System actor into the level
4. On the Geo Referencing System, set the "Origin Location" variable to the geospatial location that the Unreal Engine origin is desired to be at.
5. Make custom Unreal Engine actors for all DIS entities the project is expected to receive and handle.
   • Attach a DIS Send Component to all of the actors that are going to be DIS entities and set the parameters on the component accordingly.
     • This component will emit DIS PDUs using opened send sockets.
     • NOTE: These send sockets can be opened through the DIS Game Manager or manually via the UDP Subsystem.

General Flow

• The DIS plugin maintains a mapping within the DIS Game Manager that maps DIS Entity IDs to Unreal actors that exist in the current level.
• When an EntityStatePDU is received, it gets parsed and info it contains is utilized to check the mapping.
  • If a match is found:
    • An actor for the EntityStatePDU already exists in the level and is notified about the new information.
  • If a match is not found:
    • The DIS Game Manager looks in the DIS Enumeration Mapping asset attached to it for what actor should represent this new entity.
      • If an entity type is found in the DIS Enumeration Mapping asset that matches the entity type contained in the EntityStatePDU, the corresponding actor is spawned.
      • Otherwise nothing is done.

UDP Subsystem

• The UDP Subsystem is what is used to control UDP socket connections.
• It can be accessed via blueprints through getting the 'UDPSubsystem'.
• Notable functions:
  • Open Receive Socket
  • Close Receive Socket
  • Open Send Socket
  • Close Send Socket
  • Close All Send Sockets
  • Close All Receive Sockets
  • Get Connected Receive Socket IDs
  • Get Connected Send Socket IDs
  • Any Connected Sockets
  • Emit Bytes

• Contains event bindings for:
  • On Receive Socket Opened
  • On Receive Socket Closed
  • On Send Socket Opened
  • On Send Socket Closed
  • On Received Bytes

PDU Processor Subsystem

• The PDU Processor Subsystem is what is used to convert received bytes to their appropriate DIS PDU struct.
• It can be accessed via blueprints through getting the 'PDUProcessor'
• Notable functions:
  • Process DIS Packet

• Contains event bindings for notifying when a specific PDU type has been processed for all different PDU types currently implemented.

DIS Game Manager

• The DIS Game Manager is responsible for creating/removing DIS entities as packets are processed by the PDU Processor Subsystem. It also informs the appropriate DIS Entities when DIS packets are received that impact them. This is done through notifying their associated DIS Component.
• The DIS Game Manager has the following settings:
  • DIS Enumeration Mappings: Contains desired actor to DIS Enumeration mappings.
    • NOTE: The actors tied to DIS Enumerations have to implement the DIS Interface supplied by the GRILL DIS for Unreal plugin and also should have a DIS Component attached to them. Implement the DIS Interface functions to return the associated DIS component of the actor. Refer to the DIS Interface section below.
  • Exercise ID: The exercise ID of the DIS sim this project will be associated with.
  • Site ID: The site ID of this DIS sim.
  • Application ID: The application ID of this DIS sim.
  • Auto Connect Send Addresses: Whether or not the UDP socket(s) for sending DIS packets should be auto connected.
  • Auto Connect Send Sockets: The send sockets to automatically setup if 'Auto Connect Send Addresses' is enabled.
    • IP Address
      • The IP address to send DIS packets on. Should be a Multicast address if the socket connection type is set to Multicast.
    • Port
      • The port to send DIS packets on.
    • Send Socket Connection Type
      • The type of send socket to use. Options are: Broadcast, Multicast, and Unicast.
    • Socket Description
      • Friendly description for the the socket.
    • Buffer Size
      • The max buffer size for this socket.
  • Auto Connect Receive Addresses: Whether or not the UDP socket(s) for receiving DIS packets should be auto connected.
  • Auto Connect Receive Sockets: The receive sockets to automatically setup if 'Auto Connect Receive Addresses' is enabled.
    • IP Address
      • The IP address to receive DIS packets on. Should be a Multicast address if the socket connection type is set to Multicast.
      • NOTE: An IP address of 0.0.0.0 will listen to all incoming DIS packets for broadcast connections.
    • Port
      • The port to receive DIS packets on.
    • Socket Description
      • Friendly description for the the socket.
    • Buffer Size
      • The max buffer size for this socket.
    • Use Multicast
      • Whether or not this socket will be receiving Multicast connections.
    • Allow Loopback
      • Whether or not to receive packets that originate from our local IP.
    • Receive Data on Game Thread