Upload

HowToUse.txt

@@ -0,0 +1,17 @@
+UI Version:
+
+Simply drag and drop scripts onto the Script list or click the folder to load scripts,
+then you can double click scripts to load specific scripts, and double click functions
+to jump to them.
+
+If you'd like the clear loaded scripts or halt the current task, simply click the X.
+
+If you'd like save scripts, select scripts (CTRL+A to select all) from the Scripts list
+and click the disk to save them. Cerberus will then save each one into a folder in the same
+location as the exe.
+
+CLI Version:
+
+Simply drag and drop files or pass arguments using the command line. The Fast File extractor
+does not parse scripts that it exports automatically, so when you run Fast Files through it,
+you then need to go to the scripts and load them.

LICENSE.md

@@ -0,0 +1,70 @@
+## Last updated: May 1st, 2019
+# Cerberus End-User License Agreement (“Agreement”)
+
+Please read this End-User License Agreement (“Agreement”) carefully before using Cerberus ("Software”).
+
+***By using the Software, you are agreeing to be bound by the terms and conditions of this Agreement. This Agreement is a legal agreement between you (either an individual or a single entity ("Licensee")) and the Licensor ("Licensor") and it governs your use of the Software made available to The Licensee by the Licensor. If The Licensee does not agree to the terms of this Agreement, do not use the Software.***
+
+The Software is licensed, not sold, to the Licensee by the Licensor for use strictly in accordance with the terms of this Agreement.
+
+1. **License/Ownership**
+
+The Licensor grants the Licensee a revocable, non-exclusive, non-transferable, limited license to download, install and use the Software in accordance with the terms of this Agreement.
+
+2. **Third-Party Services**
+
+The Software may display, include or make available third-party content (including data, information, applications and other products services) or provide links to third-party websites or services (“Third-Party Services”).
+
+The Licensee acknowledges and agree that the Licensor shall not be responsible for any Third-Party Services, including their accuracy, completeness, timeliness, validity, copyright compliance, legality, decency, quality or any other aspect thereof. the Licensor does not assume and shall not have any liability or responsibility to The Licensee or any other person or entity for any Third-Party Services.
+
+Third-Party Services and links thereto are provided solely as a convenience to The Licensee and Licensee's access and use them entirely at The Licensee's own risk and subject to such third parties’ terms and conditions.
+
+3. **Restrictions**
+
+By using the Software The Licensee may:
+
+* Install and use Software in accordance with the Software documentation and pursuant to the terms and conditions of this Agreement.
+
+* Make backup copies of the Software for archival purposes.
+
+By using the Software the Licensee agrees not to:
+
+* Sell, redistribute, encumber, give, lend, rent, lease, sublicense, or otherwise transfer Software, or any portions of Software, to anyone without the prior written consent of Licensor.
+
+* Reverse engineer, decompile, dissassemble, or in anyway otherwise attempt to derive source code from the software except to the extent permittable by law.
+
+* Remove, minimize, block or modify any notices of the Licensor or its suppliers in the software
+
+* Make claims that the software is written or owned by the Licensee and not the Licensor
+
+4. **Decompiler/Disassembler Restrictions**
+
+The Software includes functionality that enables reproducing a high level respresentation of gsc/csc byte code and a decompiler that enables producing a source-like representation of gsc/csc byte code. The Licensee agrees that by using this software that the output the disassembler and decompiler produces is protected by copyright and is property of its respective owner. The Licensee agrees that they have obtained permission to disassemble and/or decompile the gsc/csc byte code. Licensor disclaims any liability for its use in violation of applicable laws.
+
+5. **Updates**
+
+The software may periodically check for updates and prompt The Licensee to install them. Updates to the software are optional. The Licensee agrees to check updates for changes to the Agreement.
+
+6. **Data Collection**
+
+The software does not collect or store any personal information about the Licensee or their use of the software.
+
+7. **Feedback/Reports**
+
+Licensee may, but is not obligated to, provide the Licensor with suggestions, bug reports, feedback, and comments regarding the Software (collectively, "Feedback"). Licensor grants to Licensee, without charge, a non-exclusive, worldwide, irrevocable, royalty-free license to reproduce, modify, create derivative works of, license, distribute and otherwise commercialize the Feedback as part of any of Licensee's offerings. Licensee agrees to not give feedback that is subject to a license that requires the Licensor to license its software or documentation to third parties because we include The Licensee's feedback in them. These rights survive this agreement.
+
+8. **Support**
+
+Because this software is “as is,” we may not provide support services for it.
+
+9. **Audits/Changes**
+
+Licensor may, at their discretions, amend this agreement at anytime. It is up to the Licensee to check the License agreement for each version. The Licensor agrees to keep the date of the latest audit at the start of the agreement for the convience of the Licensee.
+
+10. **Termination**
+
+The Licensee agrees the Licensor may, for any reason, terminate the Agreement. The Licensee agrees that the Licensor does not have the give a reason for the Agreement being terminated. The Licensor agrees that the Licensee also has these rights.
+
+11. **Disclaimer of Warranty**
+
+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.

README.md

@@ -0,0 +1,106 @@
+# Cerberus
+[![Releases](https://img.shields.io/github/downloads/Scobalula/Cerberus-Repo/total.svg)](https://github.com/Scobalula/Greyhound/releases) [![Discord](https://img.shields.io/badge/chat-Discord-blue.svg)](https://discord.gg/fGVpV39)
+
+Cerberus is a GSC/CSC Decompiler for Call of Duty: Black Ops II/III. It's main purpose is to provide access to scripts that Treyarch did not provide in the Call of Duty: Black Ops III Mod Tools and to give greater insight into how Treyarch achieved certain things, undocumented APIs, etc.
+
+If you find Cerberus useful I would appreciate it if you credited me, or if you want to support me even further you can [Donate](https://www.paypal.me/scobalula)
+
+# Features:
+* Easy to use, simply load the UI and drag/load scripts or use the CLI version for batch
+* Smart loop detection, Cerberus will check for common patterns for foreach and check variable references for for loops
+* Fast, it can decompile Black Ops III's ZM script almost instantly
+* Built-in Fast File Extractor for Black Ops III\*
+* Both a CLI and UI version
+
+\* This is only supported in the CLI program, not the UI.
+
+# Requirements
+
+* Windows 7 x86 and above
+* .NET Framework 4.7.2
+* Microsoft Visual C++ 2019 Runtime
+
+# Using Cerberus
+
+The latest version can be downloaded from the [Released](https://github.com/Scobalula/Cerberus-Repo/releases) section.
+
+By using Cerberus you are agreeing to the license terms included in the download and on the [License](https://github.com/Scobalula/Cerberus-Repo/releases) page.
+
+Once downloaded you can either use the UI or CLI version and drag and drop/load scripts. In the UI version you can double click scripts to load them and click functions to jump to them in the decompiler/disassembly. Check the "HowToUse.txt" in the download for more info on UI shortcuts, etc.
+
+# Credits:
+
+* kokole and Nukem - Basics of how the VM works from their original gsc reader
+
+# Limitations:
+
+As with any decompiler there are limitions to the output Cerberus provides.
+
+* Scripts must be dumped from a Fast File as the VM modifies the buffers. Currently only Black Ops III is supported by the built in CLI fast file extractor, for Black Ops II (which may be supported later) you can use other extractors such as master131's.
+
+* Some for loops may not be properly marked, or detected, but this is rare.
+
+* Custom GSCs compiled using Black Ops III's Mod Tools are not supported. This is a decision that will remain forever as we all know how that would end up.
+
+* Starting with Black Ops III they've started hashing almost everything, including notifies, etc. so some data will output as var_\<hash\>, etc. if it's not found in the name database. This is the hash algorithm implemented in Python:
+
+```python
+def compute_hash(value):
+    result = 0x4B9ACE2F
+    inputs = value.encode("utf8") + b'\0'
+    for byte in inputs:
+        result = 0x1000193 * (byte ^ result)
+    return result & 0xFFFFFFFF
+```
+
+* Black Ops III also introduced "debug strings". Any strings within dev blocks will output as "Dev block strings are not support".
+
+* Currently operators and compound assigments are dumped as the decompiler receives them, so check the disassembly to ensure order of operations is correct. This will be fixed in a future update.
+
+* Ternary operators are currently not supported, you can identify them with an empty if/else, you can see what it would have been by looking at the disassembly. They will be supported in a future update.
+
+* Classes for Black Ops III cannot currently be reconstructed and their output is crude at best. It should still give some insight, but keep this in mind as they are essentially glorified structs with some object orientated features. Unusued properties are scrapped among other things.
+
+* The decompiler can some times incorrectly mark blocks as childrent as other blocks, this is more an issue with cases due to being different, but it's very rare. Please file an issue either on Discord or here with the name of the script and fast file.
+
+* Not all op codes are supported for Black Ops III, if you hit an unknown op code DO NOT file an issue, I am aware of it. Both the decompiler and disassembler will just skip that op code/function.
+
+# FAQ
+
+* **I found a genuine issue with Cerberus and/or its output, how can I report it?**
+* You can file an issue either on Github or via my Discord server, pinging me on Twitter works too.
+
+* **How come some stuff is named var_49dbff, etc. but some stuff is named?**
+
+* As mentioned above Black Ops III hashes everything, a table has been built with all source gsc files I could find from CoD 4, 5, Bo1, and Bo3. Some stuff is not apart of this table.
+
+* **I compared the output from Cerberus to a script we have and some of it is different, etc?**
+
+* A decompiler will never reproduce the exact source code, but the control flow should match. An understanding of how a compiler works is a must, your code is parsed and instructions are generated matching the control, etc. With this in mind there are many ways to achieve the same thing, and so Cerberus will produce what it thinks is a good representation of the instructions.
+
+* **I tried compiling the decompiled output and it didn't work?**
+* Very rarely will a decompiler produce 100% decompilable output. The output is to be studied, not copy and pasted.
+
+* **I noticed you said custom scripts are not supported, but I really need access to my old scripts, is there any way to get them?**
+
+* I can take requests to access scripts from a map you own and need access to, but you need to make a good case to me as I'm not spending my time dumping people's maps.
+
+* **uR aPP is crAP**
+* Sorry to hear that, this is the first decompiler I've ever written so it's a big learning experience for me.
+
+# Disclaimers
+
+Cerberus is currently in a very early Alpha state but should be mostly functional. With this in mind there will be issues with Cerberus itself and the output it produces.
+
+Cerberus was developed for the users of the Black Ops III Mod Tools to provide some files/information Treyarch couldn't/didn't include with the Mod Tools. All work was done on legally obtained copies of Black Ops III and the Black Ops III Mod Tools. Most of the files it exports, are only useful to those using Black Ops III's Mod Tools. I don't aid in killing other players through walls!
+
+Cerberus is provided AS IS, do not ask how to do XYZ, etc. You need to know what you're doing, we can't hold your hand through it.
+
+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.
+
+*This tool is currently not open source and this repo just serves as documentation, issue, and release tracking. It will be open sourced down the line once I have fully completed it*