Secret Santa 2024
Original Post
Clone parser
Clone parser


This script allows you to add up to 12 projections of players into your replays. They look pretty much like regular players, but their movements are predetermined and they are not affected by physics and collisions. It also allows you to make smooth transitions between player movements in 2 different replays. Combined together this is a very useful tool for creating unique replay ideas. It currently works both on 5.55 and 5.60 alpha, however you might encounter unexpected crashes on 5.60 alpha, so use it with caution.

How it works

(Don't mind the UI color, it is the result of my theme picker script (which you can get here))

Viewing

To view a replay with clones, all you need to do is put such replay into your replays folder, and then load it from the menu. Alternatively, you can use /lsr command to load the replay, but you will need to supply folder name and specify file extension. Example: /lsr my replays/tech_demo.rpl

Creating and editing

Replay menu


To use the script UI, you'll need to have newmenu enabled. After loading the script, a new "Clone options" button will appear whenever you select a replay from the menu.

Clone menu


This is how you open the main clone menu. Here you will find 3 main options: "Record replay", "Merge with current replay", "Finalize replay". Let's go over each of these.

Record replay

This is where most of the magic happens. You'll also find that this is the biggest menu with lots of options.

Record replay menu



Player options
This is where you select what happens to each player and clone present in the selected replay.
The checkmark next to each player name determines whether to record the player or not. Right under that you can choose which index to assign to a new player (0 is tori, 1 is uke, etc), and whether to convert a player to a clone or not. If the player is already a clone, this will instead determine whether to convert a clone into a real player (referred to as "bout" in replay files). Right under that is a feature that was added due to popular demand, the clone opacity. This only works if the player is a clone, or gets converted into a clone, and determines their opacity in the resulting replay.

Transition options
Transitions are a tool for you to splice together multiple replays at certain frame cut offs. These only work if you set replay recording to start or to end at a certain frame other than the default values. The first checkmark right next to the word "transition" determines whether to record a replay with a transition or not
  • Transition types:
    • Fade is a type of transition that changes clones opacity from 0 to the value chosen over the duration of the transition.
    • Shift is a type of transition that changes player position over the duration of the transition. This transition works for both bouts and clones. Depending on whether "transition from current" has been selected or not, it either transitions all of the positions from world's (0, 0, 0) coordinates, or from player positions in the current replay at the given frames. More on that later.
    • Scale is a type of transition that changes clone over the duration of the transition. Depending on whether "transition from current" has been selected or not, it either transitions all of the sizes from (0, 0, 0), or from player sizes in the current replay at the given frames. More on that later.
  • Transition timer determines the duration of the transition. If you choose to start the recording on frame 50, and set the timer to 50, the transition will take place from frame 50 to frame 100.
  • If transition from current is selected, then for shift and scale transitions the script will record current replay player positions for the frames transition takes place. After this, for every frame of the transition it will pick a value between the current replay position and/or size, and recorded replay position and/or size to smoothly transition from current replay into recorded replay. Also it is important to remember that for this option, the script will attempt to transition players and clones with indexes from the current replay that match the ones you selected for the output. For example, if you want to transition player 0 from current replay, but you also chose to transition them into a clone, then this option will atttempt to look for a clone 0 and transition from their position or size.
  • Transition start doesn't work as intended in this version, and will probably be changed later.

Replay options
Start from determines when to start the recording, 0 being the start of the replay. Start transitions will only happen if this value does not equal 0.
End at determines when to end the recording. If set to 0, the replay will stop recording at the end of the replay. End transitions will only happen if this value does not equal 0 (or matchframes).
Delay detmines the resulting replay frame offset. If delay is set to a positive number, the replay will start a bit later. If it's set to a negative number, the replay will skip the first few frames and start after.
Always remember to input some sort of an output replay name, otherwise the resulting replay will not be saved.

Once you start the recording, the script will load the replay and go through it, recording current game state for each frame. Once it's done, the resulting replay will load so that you can check if everything got recorded like you wanted.

Merge with current replay

Merge menu


This is where you take your recorded replays and splice them together.
For the "add players" option, the script will add and reindex all players from selected replay to the replay currently open in the background. Be careful though, because if a replay has more than 4 actual players it leads to unexpected results. Also the clones after 12th will either appear partially, or not at all.
For the "overwrite players" option, the script will overwrite player and clone information in the current replay with information from the second replay for every frame. If you do this with replays that haven't been properly recorded first, this might result in players jumping back and forth between the two replays.

Finalize replay

Finalize menu


This option will remove any extra information that may have been used to make editing the replays easier. Use this after finishing work on the replay to reduce its size.

Swap menu

Swap menu


When watching a replay with clones, you have an option to click on any clone head to bring up the swap menu. This is a quick alternative to recording a replay when you just need to swap one clone and one player in place. This can be used to record movements for a clone once you're done with player movements. It's also useful for when you've clipped a real bodypart with a clone bodypart, and you want to quickly record the collision to avoid ghosting.
In the "swap with" section you can choose which player to swap the selected clone with. Alternatively you can click on the players heads to select them.
In the "from" section you can choose when the swap occurs. If you choose start, it will record all of the player and clone movements from the start of the replay, and turn the clone into a real player and vice versa. If you choose "current frame", the swap in place will occur on the current world frame. As always, don't forget about the output name!

Saving replay

Save replay


If the replay has clones, a new "Save with clones" button will appear in the save replay menu. This option can take quite a long time, and your game will appear to be frozen for the duration. Do not panic, let it cook.

Under the hood

The way this technology works is for the clones, we write additional lines to the replay. To begin with, in the header of the replay, right after the lines where we define regular players with BOUT 0; nickname, we define clones with similar syntax: CLONE 0; nickname.

For each frame, additionally to the usual replay info we also put information about clones.
  • CLONEPOS dictates current position of all of the clone bodyparts
  • CLONEJOINTPOS dictates current position of all of the clone joints
  • CLONEQAT dictates rotation of clone bodyparts and joints, depending on which bodypart the joint is linked to (e.g. neck is linked to the head, wrist is linked to the hand, etc)
  • CLONESIZE dictates bodypart sizes of the clone
  • CLONEJOINTSIZE dictates joint sizes of the clone
  • CLONECRUSH indicates dismembers, and colors specified joints into the clone's blood color
  • CLONEFRACT same as dismembers, indicates clone fractures
  • CLONEALPHA indicates current clone opacity
  • CLONEGRIP is used to store metadata about player grips, used when swapping a clone back into a player and gets removed by the finalize function
  • CLONEJOINT is used to store metadata about player joint states, used when swapping a clone back into a player and gets removed by the finalize function
  • CLONELINVEL is used to store metadata about player linear velocity, used when swapping a clone back into a player and gets removed by the finalize function
  • CLONEANGVEL is used to store metadata about player angular velocity, used when swapping a clone back into a player and gets removed by the finalize function

When loading a replay with the script, it looks for any clones in the header of the replay. If it finds them, for each frame of the replay it then looks for these lines and updates clone bodypart and joint state accordingly. For ghosts, it reads the future clone movements and draws them closely resembling default ghost.

Notes to remember
.
  • It is important to remember that the limit for new 3d objects is 512. This means that you can only have up to 12 clones, and even less than that if they have a lot of 3d items. If you've reached this limit and some of the players stop showing up, consider turning off 3d objects with /opt obj 0. For ghosts, if the number of 3d objects on the screen has exceeded 256, it will hide actual players whenever the ghosts are visible.
  • You need to keep in mind that the script only records the length of the match, and there are still 100 extra frames after the end of the match that get skipped. As such, clones will be frozen in place at the end of the match. If you want the clones to keep moving until after the match is over, set the replay matchframes 100 frames longer while you're working on it, and then change it back once you're done.
  • When creating clone replays, it takes a while for the output file to show up in the replay list. If you want to load it before it appears on the list, you can either restart the game or load the result replay with the /lsr command.
  • Clones only get loaded when you open the replay from the menu or use lsr command. Scrolling through replays with keybinds or opening a replay from file explorer will not load clones.
  • Replays with clones take up significantly more space than regular replays, so remember to clean up your WIPs after you're done.
  • When recording replays to merge them later, it is a good idea to set their indexes to go from 0 up and to have them not overlap unless needed.
  • While I've been working on this script for almost two months, it is a very ambitious project for one single me. As such, you might encounter bugs and weird behavior. Please do not hesitate to report any of that to me whether in this thread, in PMs, or in Discord (Serge#8687).

Examples of things you can do

Race vs local ghost


Motion blur


Pop in and out


Grow in size


Morphing into a different player



Chat commands
.
  • /lsr|loadscriptedreplay path to replay/replay name.rpl - loading scripted replays
  • /ssr|savescriptedreplay replay name - saving scripted replays. The syntax is different from lsr command, and the replays get saved to the "my replays" folder
  • /lc|loadclone 0-12 name - same as the lp|loadplayer command, but for clones
  • /oc|optclones 0|1 - to enable/disable clone visibility. Might work wonky with some of the transitions on this version

While this new tech is definitely something toribash hasn't seen before, it only shows a portion of the full potential of this tech. And if this script is liked by the community I might keep making updates to it, further pushing the possibilities. For now though I am super excited to see what you guys come up with. If there's anything Toribash has always had, it's talented people that come up with the most crazy stuff. Go crazy, make me proud. I leave you with this little gif that you might have already seen.


P.S. I know right now the guide looks like a big and scary wall of text. I will try to make edits and updates to this guide to make it more accessible.

1.0.1 update: fixed odd behavior when merging replays with indexes that dont start at 0
Attached Files
clone_parser.lua (138.6 KB, 11 views)
clone_parser_v1.0.1.lua (139.2 KB, 38 views)
Last edited by AssassinPro; Mar 7, 2023 at 01:30 PM.
golf
LOL

yeah idk this shit is just beyond crazy good it should be deemed a warcrime that you're not legend already Sassy


MASSIVE props
Jun 2, 2023 - .best. day. ever.
Originally Posted by Xioi View Post
yeah idk this shit is just beyond crazy good it should be deemed a warcrime that you're not legend already Sassy

I completely agree, he is a legend in our hearts tho. (for now at least)
d o r p
destruidorp4
destruidor
toribash for life
I randomly check the forum for the first time in a year and this is what I see

Contact sir to have it implemented.
Will nominate for yellow this is fantastic