Skip to content

Commit

Permalink
[Flavor] Add examples to documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@ScribbleTAS
ScribbleTAS committed Dec 25, 2024
1 parent e02b605 commit 77d5871
Showing 1 changed file with 124 additions and 12 deletions.
136 changes: 124 additions & 12 deletions src/main/java/com/minecrafttas/tasmod/playback/tasfile/flavor/SerialiserFlavorBase.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@
import com.minecrafttas.tasmod.virtual.VirtualMouse;

/**
* <p>The base class of a flavor.
* <p>The base class of a flavor
*
* <p>All serialisation and deserialisation is broken apart into functions whenever possible,<br>
* with the intention of allowing small changes to the existing syntax.
Expand Down Expand Up @@ -116,32 +116,61 @@ public abstract class SerialiserFlavorBase implements Registerable {
*/

/**
* <h3>Example</h3>
* <pre>
* ##################### TASfile ####################
* </pre>
* @return The very top of the header
*/
protected String headerStart() {
return createCenteredHeading("TASfile", '#', 50);
}

/**
* The end of the header, used for detecting when the header stops
* <p>The end of the header, used for detecting when the header stops
* <h3>Example</h3>
* <pre>
* ##################################################
* </pre>
* @return The end of the header
*/
protected String headerEnd() {
return createPaddedString('#', 50);
}

/**
* <p>Serialises the flavor of this file, the enabled file commands and other metadata.
* <p>{@link #serialiseFlavorName(List)}
* <p>Serialises the flavor of this file, the enabled file commands and other metadata
* <h3>Tree</h3>
* <pre>
* serialiseHeader
* ├── {@link #headerStart()} // The start of the header
* ├── {@link #serialiseFlavorName(List)} // The name of the flavor
* ├── {@link #serialiseFileCommandNames(List)} // The names of the enabled file commands
* ├── {@link #serialiseMetadata(List)} // The metadata of this movie
* │ ├── {@link #serialiseMetadataName(List, String)} // The metadata extension name
* │ └── {@link #serialiseMetadataValues(List, LinkedHashMap)} // All values in the extension
* └── {@link #headerEnd()} // The end of the header
* ├── {@link #headerStart()}
* ├── {@link #serialiseFlavorName(List)}
* ├── {@link #serialiseFileCommandNames(List)}
* ├── {@link #serialiseMetadata(List)}
* │ ├── {@link #serialiseMetadataName(List, String)}
* │ └── {@link #serialiseMetadataValues(List, LinkedHashMap)}
* └── {@link #headerEnd()}
* </pre>
* <h3>Example</h3>
* <pre>
* ##################### TASfile #################### // {@link #headerStart()}
* Flavor: beta1 // {@link #serialiseFlavorName(List)}
* FileCommand-Extensions: tasmod_desyncMonitor@v1, tasmod_options@v1, tasmod_label@v1 // {@link #serialiseFileCommandNames(List)}
*
* --------------------- Credits -------------------- // {@link #serialiseMetadataName(List, String)}
* Title:Insert TAS category here // {@link #serialiseMetadataValues(List, LinkedHashMap)}
* Author:Insert author here
* Playing Time:00:00.0
* Rerecords:0
*
* ----------------- Start Position -----------------
* x:-32.577311363268976
* y:56.0
* z:-4.457057187505265
* pitch:29.25007
* yaw:-88.80094
*
* ################################################## // {@link #headerEnd()}
* </pre>
* @return List of lines containing the header
*/
Expand All @@ -156,16 +185,28 @@ public List<String> serialiseHeader() {
}

/**
* <p>How the flavor name is serialised.
* <p>How the flavor name is serialised
* <p>You normally don't have to edit this,<br>
* as the flavor name is taken from the extension name.
* <h3>Example</h3>
* <pre>
* Flavor: beta1
* </pre>
*
* @param out The serialised lines, passed by reference
*/
protected void serialiseFlavorName(List<String> out) {
out.add("Flavor: " + getExtensionName());
}

/**
* <p>Adds the file commands that are enabled to the lines
* <h3>Example</h3>
* <pre>
* FileCommand-Extensions: tasmod_label@v1, tasmod_desyncMonitor@v1
* </pre>
* @param out The serialised lines, passed by reference
*/
protected void serialiseFileCommandNames(List<String> out) {
List<String> stringlist = new ArrayList<>();
List<PlaybackFileCommandExtension> extensionList = TASmodAPIRegistry.PLAYBACK_FILE_COMMAND.getEnabled();
Expand All @@ -176,6 +217,25 @@ protected void serialiseFileCommandNames(List<String> out) {
out.add("");
}

/**
* <p>Serialises the metadata to the header of the TASfile
* <h3>Example</h3>
* <pre>
* --------------------- Credits --------------------
* Title:Insert TAS category here
* Author:Insert author here
* Playing Time:00:00.0
* Rerecords:0
*
* ----------------- Start Position -----------------
* x:-32.577311363268976
* y:56.0
* z:-4.457057187505265
* pitch:29.25007
* yaw:-88.80094
* </pre>
* @param out
*/
protected void serialiseMetadata(List<String> out) {
if (!processExtensions)
return;
Expand All @@ -189,16 +249,64 @@ protected void serialiseMetadata(List<String> out) {
}
}

/**
* <p>Serialises only the name of the metadata section
* <h3>Example</h3>
* <pre>
* --------------------- Credits --------------------
* </pre>
* @param out The lines passed in by reference
* @param name The name to process
*/
protected void serialiseMetadataName(List<String> out, String name) {
out.add(createCenteredHeading(name, '-', 50));
}

/**
* <p>Serialises only the values of the metadata section
* <h3>Example</h3>
* <pre>
* Title:Insert TAS category here
* Author:Insert author here
* Playing Time:00:00.0
* Rerecords:0
* </pre>
* @param out
* @param data
*/
protected void serialiseMetadataValues(List<String> out, LinkedHashMap<String, String> data) {
data.forEach((key, value) -> {
out.add(String.format("%s:%s", key, value));
});
}

/*
___ _____ _ _ ____ ____ _ _ ____
/ __)( _ )( \( )(_ _)( ___)( \( )(_ _)
( (__ )(_)( ) ( )( )__) ) ( )(
\___)(_____)(_)\_) (__) (____)(_)\_) (__)
*/

/**
* <p>Serialises a list of inputs into a list of strings
* <h3>Tree</h3>
* <pre>
* serialise
* └── {@link #serialiseContainer(BigArrayList, TickContainer)}
* ├── {@link #serialiseKeyboard(VirtualKeyboard)}
* ├── {@link #serialiseMouse(VirtualMouse)}
* ├── {@link #serialiseCameraAngle(VirtualCameraAngle)}
* ├── {@link #serialiseInlineComments(List, List)}
* │ └── {@link #serialiseFileCommandsInLine(List)}
* ├── {@link #serialiseEndlineComments(List, List)} // Same as serialiseInlineComments
* │ └── {@link #serialiseFileCommandsEndLine(List)} // Unused
* └── {@link #mergeInputs(BigArrayList, List, List, List, List)}
* </pre>
* @param inputs The inputs to serialise
* @param toTick The tick where to stop, used for partial serialisation by savestates. -1 to serialise all
* @return The list of lines
*/
public BigArrayList<String> serialise(BigArrayList<TickContainer> inputs, long toTick) {
BigArrayList<String> out = new BigArrayList<>();

Expand Down Expand Up @@ -253,6 +361,10 @@ protected String serialiseFileCommandsInLine(List<PlaybackFileCommand> fileComma
return String.join(" ", serialisedCommands);
}

protected String serialiseFileCommandsEndLine(List<PlaybackFileCommand> fileCommands) {
return serialiseFileCommandsInLine(fileCommands);
}

protected List<String> serialiseKeyboard(VirtualKeyboard keyboard) {
List<String> out = new ArrayList<>();

Expand Down

0 comments on commit 77d5871

Please sign in to comment.