Skip to content

Commit

Permalink
Housekeeping
Browse files Browse the repository at this point in the history
  • Loading branch information
m6c7l committed Sep 14, 2019
0 parents commit f443531
Show file tree
Hide file tree
Showing 151 changed files with 20,706 additions and 0 deletions.
28 changes: 28 additions & 0 deletions LICENSE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
This software is licensed under the MIT license, which gives everyone the right to use and distribute the software, either in binary or source code format, as long as the copyright license is retained in the source code.

The copyright for different parts of the software can be held by different people and organizations. Such software may be separately licensed by its copyright holder, hence the use of such software must be in accordance with its license terms.

**MIT License**

```
Copyright (c) 2018 m6c7l
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
```

71 changes: 71 additions & 0 deletions docs/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,71 @@
# Playmate

A Practical Submarine Simulator that is written in Java ...

<p align="center">
<img src="playmate.png">
</p>

## What is Playmate?

Playmate is a submarine simulator designed for training in target motion analysis (TMA) exclusively using the contact evaluation plot (CEP). The CEP is a time-bearing diagram on a submarine showing the trace of sound emissions tracked by sonar. Furthermore, the CEP is a valuable tool for planning own sub's movement in tactical and abrupt situations. Hence, reading the CEP correctly is an important skill for sonar personnel and the officer of the watch when operating submerged. For sharpening the skills of CEP reading extensive training is crucial. And there, Playmate comes into play.

## Why this name?

The APP-7 (Joint Brevity Words Publication) defines "playmate", inter alia, as follows: "a submarine with which I am co-operating". The brevity word "playmate" is mostly used by aircraft for tactical radio communication while initiating an exercise with a submarine. Because of the all-around bird's-eye view in the simulator, in particular at charts, one could imagine being in an aircraft staying on top of the submarine playing with. That's it.

## What is here?

This repository contains the Java codebase of Playmate and a simple Ant script for building it. In total, the codebase got about 130 classes, roughly 15000 lines of code and more than 1000 lines for comments. However, about half of the codebase can be considered as being a library providing more or less common functionality.

A ready-to-go version of Playmate is available on the [release page](https://github.com/m6c7l/playmate/releases), everything else is a story of an Ant.

## How to use it?

Playmate runs on every PC with Java 1.6+ installed. The graphical user interface (GUI) is optimized for usage with a wheeled mouse.

In general, the workflow in Playmate is as follows:

1. Select a chart with your desired geographical area of operation.
2. Drag the own ship to the desired position in the chart.
3. Drag assets to the desired positions in the chart. If necessary, adjust the initial position of any asset.
4. For any asset, change the speed and heading or set waypoints respectively.
5. Select the Assets tab and the CEP window before starting the simulation.
6. Select exercise in the menu to hide anything in the GUI usually not available on a submerged submarine.
7. Try to estimate distance, type of approach, angle on the bow and heading for all assets visible in the CEP.
8. Stop the simulation and compare your estimations with the ground truth at any time using the ruler and time control.

The [quick reference guide](/sources/doc/playmate.pdf) gives an overview of all control options within the GUI.

## Why using it?

Well, it depends. Perhaps you want to ...

- deal with tricky situations, e. g. when the XO orders "prepare periscope depth" in an area with a high level of traffic, knowing you have to be on periscope depth at the latest in 15 minutes to receive the next VLF broadcast.
- be able to give the CO asking for vessels within 4000 yards just after one change, of course, a convincing answer at any time.
- find the optimal course to intercept a suspect far away by using a steady bearing.
- impress the guy next to you responsible for TMA with decent target data acquired with your CEP magic and some mental math.
- be able to build up and maintain a robust surface picture by looking exclusively at the sound traces of vessels and their trackers from sonar respectively.
- increase your awareness of the importance for own sub's maneuvers supporting most kinds of TMA.
- avoid the need to occupy an expensive shore-side submarine simulator for basic CEP training.
- reconstruct and replay a situation picture you are curious about while having the opportunity to observe figures like resultant speed across (RSA), distance off track (DOT), closest point of approach (CPA), distance and so on for each asset.

## What is not here?

Neither the fundamentals of submarine operations and tactics nor characteristics and technical details about submarines and ships are obtainable by using Playmate or by investigating the codebase.

## Anything else?

1. Initially, I created a console-only predecessor of Playmate for my training a few years ago. Since then the project grew and became a reasonable simulation and reconstruction tool.
2. The codebase could be a good starting point for more advanced simulators or even games.
3. The Java package names in the codebase are (probably) self-explanatory. For the implementation, I picked just a few design patterns, mostly model-view-controller (MVC) and observer.
4. The tactical view in Playmate is not yet finished.
5. To add charts and assets edit the corresponding XML file in the data folder. Just use an existing entry in that file as a template.
6. Due to the project size and time constraints Playmate will not be developed any further.
7. And last but not least, Dolphin 37 & 38.

## Further reading

* MARCOM Northwood UK -- [NATO’s advanced Anti-Submarine Warfare Exercise Dynamic Manta 2017 concludes](https://mc.nato.int/media-centre/news/2017/natos-advanced-antisubmarine-warfare-exercise-dynamic-manta-concludes.aspx)
* United States Navy -- [Operations Specialist, Vol. 01, Ch. 10 (Plotting)](https://www.globalsecurity.org/military/library/policy/navy/nrtc/14308_ch10.pdf)
* Rodrigo da Silva Vieira -- [Towards a game-based periscope simulator for submarine officers tactical training](https://calhoun.nps.edu/handle/10945/49409)
Binary file added docs/playmate.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
42 changes: 42 additions & 0 deletions sources/build.xml
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
<!--
Copyright (c) 2018, Manfred Constapel
This file is licensed under the terms of the MIT license.
-->

<project name="playmate" basedir="." default="main">

<property name="sources.dir" value="src"/>
<property name="build.dir" value="."/>
<property name="classes.dir" value="${build.dir}/bin"/>
<property name="jar.file" value="${build.dir}/${ant.project.name}.jar"/>
<property name="main.class" value="de.m6c7l.playmate.Start"/>

<path id="classpath">
<pathelement location="${classes.dir}"/>
</path>

<target name="clean">
<delete dir="${classes.dir}"/>
<delete file="${jar.file}"/>
</target>

<target name="compile">
<mkdir dir="${classes.dir}"/>
<javac includeantruntime="false" srcdir="${sources.dir}" destdir="${classes.dir}">
<classpath refid="classpath"/>
</javac>
</target>

<target name="jar" depends="compile">
<jar jarfile="${jar.file}" basedir="${classes.dir}">
<manifest>
<attribute name="Main-Class" value="${main.class}" />
</manifest>
<fileset dir="${sources.dir}" excludes="**/*.java" />
</jar>
<delete dir="${classes.dir}"/>
</target>

<target name="main" depends="clean,jar"/>

</project>
240 changes: 240 additions & 0 deletions sources/data/assets.xml
Original file line number Diff line number Diff line change
@@ -0,0 +1,240 @@
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<assets>

<asset>
<id>ASL-1</id>
<name>ASL-1</name>
<class>ASL</class>
<type>ASL</type>
<loa>100.5</loa>
<boa>15.4</boa>
<draft>4.1</draft>
<maxspeed>9.2</maxspeed>
<flag>de</flag>
<military>true</military>
</asset>

<asset>
<id>ARLHM-1</id>
<name>ARLHM-1</name>
<class>ARLHM</class>
<type>ARLHM</type>
<loa>100.5</loa>
<boa>15.4</boa>
<draft>4.1</draft>
<maxspeed>7.5</maxspeed>
<flag>de</flag>
<military>true</military>
</asset>

<asset>
<id>MHC-1</id>
<name>MHC-1</name>
<class>MHC</class>
<type>MHC</type>
<loa>54.4</loa>
<boa>9.2</boa>
<draft>2.5</draft>
<maxspeed>9</maxspeed>
<flag>de</flag>
<military>true</military>
</asset>

<asset>
<id>PGGFM-1</id>
<name>PGGFM-1</name>
<class>PGGFM</class>
<type>PGGFM</type>
<loa>57.6</loa>
<boa>7.8</boa>
<draft>2.6</draft>
<maxspeed>20</maxspeed>
<flag>de</flag>
<military>true</military>
</asset>

<asset>
<id>FFGHM-1</id>
<name>FFGHM-1</name>
<class>FFGHM</class>
<type>FFGHM</type>
<loa>143</loa>
<boa>17.4</boa>
<draft>6.9</draft>
<maxspeed>14</maxspeed>
<flag>de</flag>
<military>true</military>
<sonar>true</sonar>
</asset>

<asset>
<id>FFGHM-2</id>
<name>FFGHM-2</name>
<class>FFGHM</class>
<type>FFGHM</type>
<loa>130</loa>
<boa>14.5</boa>
<draft>6.5</draft>
<maxspeed>15</maxspeed>
<flag>de</flag>
<military>true</military>
<sonar>true</sonar>
</asset>

<asset>
<id>DDGM-1</id>
<name>DDGM-1</name>
<class>DDGM</class>
<type>DDGM</type>
<loa>133.2</loa>
<boa>14.3</boa>
<draft>6.1</draft>
<maxspeed>16</maxspeed>
<flag>de</flag>
<military>true</military>
<sonar>true</sonar>
</asset>

<asset>
<id>FFGHM-3</id>
<name>FFGHM-3</name>
<class>FFGHM</class>
<type>FFGHM</type>
<loa>138.9</loa>
<boa>16.7</boa>
<draft>6.8</draft>
<maxspeed>14.5</maxspeed>
<flag>de</flag>
<military>true</military>
<sonar>true</sonar>
</asset>

<asset>
<id>SSK-1</id>
<name>SSK-1</name>
<class>SSK</class>
<type>SSK</type>
<loa>56</loa>
<boa>7</boa>
<draft>6.5</draft>
<maxspeed>
<surfaced>6</surfaced>
<dived>10</dived>
</maxspeed>
<mod>100</mod>
<flag>de</flag>
<military>true</military>
</asset>

<asset>
<id>SSK-2</id>
<name>SSK-2</name>
<class>SSK</class>
<type>SSK</type>
<loa>48.6</loa>
<boa>4.6</boa>
<draft>4.5</draft>
<maxspeed>
<surfaced>5</surfaced>
<dived>8.5</dived>
</maxspeed>
<mod>100</mod>
<flag>de</flag>
<military>true</military>
</asset>

<asset>
<id>TMF-1</id>
<name>TMF-1</name>
<class>TMF</class>
<type>TMF</type>
<loa>89.75</loa>
<boa>30.47</boa>
<draft>3.9</draft>
<maxspeed>19</maxspeed>
<flag>se</flag>
<military>false</military>
</asset>

<asset>
<id>TMO-1</id>
<name>TMO-1</name>
<type>TMO</type>
<loa>124</loa>
<boa>20</boa>
<draft>5.5</draft>
<maxspeed>7</maxspeed>
<flag>gi</flag>
<military>false</military>
</asset>

<asset>
<id>MPA-1</id>
<name>MPA-1</name>
<role>ASW</role>
<length>35.6</length>
<wingspan>30.4</wingspan>
<ceiling>8625</ceiling>
<speed>
<cruise>110</cruise>
<max>211</max>
</speed>
<military>true</military>
</asset>

<asset>
<id>TCA-1</id>
<name>TCA-1</name>
<length>9.3</length>
<wingspan>11.9</wingspan>
<ceiling>7620</ceiling>
<speed>
<cruise>101</cruise>
<max>111</max>
</speed>
<military>false</military>
</asset>

<asset>
<id>AH-1</id>
<name>AH-1</name>
<role>ASW</role>
<length>22.8</length>
<rotor>
<type>main</type>
<diameter>18.6</diameter>
</rotor>
<ceiling>4575</ceiling>
<maxspeed>86</maxspeed>
<military>true</military>
</asset>

<asset>
<id>AH-2</id>
<name>AH-2</name>
<role>ASW</role>
<length>11.3</length>
<rotor>
<type>coaxial</type>
<diameter>15.9</diameter>
</rotor>
<ceiling>5000</ceiling>
<maxspeed>69</maxspeed>
<military>true</military>
</asset>

<asset>
<id>TH-1</id>
<name>TH-1</name>
<length>16.6</length>
<rotor>
<type>tandem</type>
<diameter>14.9</diameter>
</rotor>
<ceiling>5000</ceiling>
<maxspeed>69</maxspeed>
<military>true</military>
</asset>

</assets>
Loading

0 comments on commit f443531

Please sign in to comment.