Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/picalines/outer-scout-blender

A cinematic toolbox for Outer Wilds & Blender
https://github.com/picalines/outer-scout-blender

blender blender-addon compositing machinima outer-wilds

Last synced: 1 day ago
JSON representation

A cinematic toolbox for Outer Wilds & Blender

Awesome Lists containing this project

README 

        
# Outer Scout Blender



A frontend for the [Outer Scout](https://github.com/Picalines/outer-scout) mod. This addon allows you to make cinematic shots in Outer Wilds and import them into Blender!



![the Outer Scout thumbnail](https://github.com/Picalines/outer-scout/raw/master/thumbnail.png)



## Basic usage example



### 1. Open Blender and Outer Wilds at the same time



> [!NOTE]

> The mod makes the game work in the background without a pause. This is necessary so that the two programs can interact at any time



### 2. Create Outer Scout scene



Get to the desired location in Outer Wilds and click "Create Scene" in the scene properties tab





  the create button

  desired location




### 3. Import the planet model



See more in the [asset extraction guide](#extracting-game-assets). Planet models are only needed for convenient positioning of your objects - they shouldn't be on the final render of the scene





  import button

  imported body




### 4. Make a camera



Put the camera in Blender and animate it. In addition to position and rotation, you can animate its `focal length`, `lens shift`, `clip start/end` and `sensor size`. You can try adding camera shake using the [camera shakify addon](https://github.com/EatTheFuture/camera_shakify)





  camera configuration

  camera animation




> [!TIP]

> A file path that starts with `//` is relative to your `.blend` file. No need to open the file dialog!



### 5. Record the footage



Click the record button in the scene properties tab. After recording, all configured cameras will receive a background with the recorded video





  the record button

  imported background




### 6. Setup compositor



The main idea of the mod and addon is to render blender models *on top* of the game's footages. To do this, click on the button and add the generated node group to the compositor tree



After that, you can do anything with your scene - you can even add effects on the footages of the game using the compositing nodes, or pull them into some editing program. You can make complex scenes with [multiple cameras](https://docs.blender.org/manual/en/latest/animation/markers.html#bind-camera-to-markers), and the addon will generate the necessary nodes for you





  generate nodes button

  compositing tab




## Requirements



- Outer Wilds patch 15

- Blender 4.2

- [Outer Scout mod](https://outerwildsmods.com/mods/outerscout/) (available in the [mod manager](https://outerwildsmods.com/mod-manager/)!)

- [FFmpeg](https://ffmpeg.org/about.html) for video recording. See the [mod's requirements](https://github.com/Picalines/outer-scout/blob/master/README.md#requirements) for more details

- [AssetStudio](https://github.com/Perfare/AssetStudio) for planet model extraction



## Installation



- Go to the [Releases tab](https://github.com/Picalines/outer-scout-blender/releases) and download the `outer_scout.zip` file of the latest version

- Open Blender, `Edit > Preferences > Get Extensions`

- Click on the arrow in the upper right corner, `Install from Disk...`

- Select the archive you downloaded earlier



See the [asset extraction section](#extracting-game-assets) to learn more about the addon settings



## Additional Features



### Game Object Replay



Use this feature to add interaction between game objects and your blender models:

1. Create an Empty in the Blender, and give it the name of the Unity object from Outer Wilds in the Outer Scout panel. The easiest way to find out the name of an object is using [Unity Explorer](https://outerwildsmods.com/mods/unityexplorer/)

2. Set the `Unity Object Mode` to `Existing`. In this mode, the mod will not create a new empty `UnityEngine.GameObject`, but search for an existing one

3. Specify the path to the file where the mod will record information about this object on each frame



After that, the `Transform Mode` property will appear, which tells the mod what to do after the next recording starts:

- In `Record` mode, the mod will capture the transformation parameters of the object on each frame of the animation, and then import them as key frames of the blender

- In `Replay` mode, the mod, on the contrary, imports the key frames of the blender into the game and assigns them to the object on each frame of the animation



*Yes, it's a bit complicated*, but the final algorithm is like this:

- Create an object in `Record` mode and hit the "record" button in the scene properties tab

- The mod *automatically* sets all `Record` objects to `Replay`

- Now you can animate your blender models based on the position of something from the game! *Dreams come true!*





  game object config

  imported keyframes




### HDRI recording



You can select the `Equirectangular` type in the camera settings. In this case, the mod will record something like a 360 video from the point of that camera, which is suitable for creating [HDRI](https://docs.blender.org/manual/en/latest/render/lights/world.html) in a Blender



The "Generate HDRI nodes" button generates the desired node group to be added to the world shader. There can only be one HDRI camera on one scene





  equirectangular camera

  suzanne with hdri




### Depth recording



The mod can record several textures from one camera at once. In this way, you can get both a color channel and a depth channel at the same time. The latter is used in the generated compositing nodes to put the blender object "[behind](https://docs.blender.org/manual/en/latest/compositing/types/color/z_combine.html)" the game object



> [!WARNING]

> This feature works well only when your object is blocked by something from the foreground. Most likely, I incorrectly implemented the conversion of the Unity depth to Blender

>

> The result depends on the [clip planes](https://docs.blender.org/manual/en/latest/render/cameras.html#:~:text=it%20off%2Dcenter.-,Clip%20Start%20and%20End,-The%20interval%20in). The greater the distance, the worse





  depth config

  cropped render




### Miscellaneous



#### `Sidebar > View > Outer Scout`



- Toggle the planet model visibility

- Warp the player to a position in the game corresponding to the position of the 3D cursor

- Reposition the scene using the 3D cursor



#### Planet sectors



The planets in the game are divided into separate sectors by points of interest to optimize their loading time. When creating a scene, you can stand in the right place in the game, and by default the addon imports only those sectors in which the player is located



This saves performance, especially on large planets with many separate enclosed rooms - inaccessible locations will be skipped. If desired, you still have the option to import the entire planet, or select a planet not according to the player's position (see the [asset extraction guide](##extracting-game-assets) for details)



#### Planet model animation



You can try to animate the rotation of the planet object, rather than the camera itself - then you will be able to make an orbit flight! *Just don't read [the code](https://github.com/Picalines/outer-scout-blender/blob/aa85ec6b886e7feecec7d7a8a4e9ff652deb775b/operators/record.py#L259) of this thing*



## Extracting game assets



In order to import planet models into Blender you need to extract mesh assets from the game



1. Open the [AssetStudio](https://github.com/Perfare/AssetStudio)



2. Click `File > Load Folder`



3. Select your Outer Wilds's data folder (`OuterWilds_Data`)



> [!TIP]

> For Steam users, `Properties... > Installed Files > Browse...`



4. `Options > Export options`, set the `Group exported assets by` option to `container path`



  Other export options (optional)

  other export options



> [!IMPORTANT]

> There are two folders with assets: one for `.fbx` files (*bodies*), and another one for `.obj` files (*extracted*). `.fbx` contains static planet assets, and they have a low quality. `.obj` is for streamed assets - they have high quality, *but there're a lot of them*

>

> 


>   asset folders

> 


>

> We use `.fbx` to find out the structure of the planet's assets, and then put in the right places those `.obj` that we could find in the second folder. The addon does this in a separate `.blend` file, and then links it to your main file. In subsequent times `.blend` of the planet is being reused

>

> At the time of the first generation of the planet `.blend` file, you need to be on that planet in the game. This is necessary so that the addon receives information about streamed assets that is not available in `.fbx` files. The addon will save it to the *bodies* folder in a `.json` file, after which you can safely close the game. You can always edit the planet file to your needs - the addon only cares about its name

>

> Generation of the `.blend` file can take up to several minutes, while the main Blender window will not respond - this is normal. Planet generation takes place in a background process, and you should be able to see the progress console. The addon will not be able to find some assets - *this is also normal*

>

> The generation step is long, but it needs to be endured only once - in subsequent times the addon will find the `.blend` file in the *bodies* folder and reuse it



5. `Filter type > Mesh`



6. `Export > Filtered assets` to the *extracted* assets folder



7. Select the planets of interest, and then `Model > Export selected objects (split)` to the *bodies* folder



export planets



> [!NOTE]

> All the planets can be put in one *bodies* folder - the addon will only search for `.fbx` and `.blend` files in there by the name of the desired planet. You don't need to change these paths more than once after installation



> [!WARNING]

> Each planet subtree must have object with `_Body` postfix within. You *can't* select the `SolarSystemRoot`, because each planet should be in a separate `.fbx` file



> [!NOTE]

> AssetStudio will emit the texture `.png` files along side with `.fbx`, but they're not required for this addon.