rosarymala/armok-vision

A 3d realtime visualizer for Dwarf Fortress

Armok Vision

Forum thread | Screenshots

A 3d realtime visualizer for Dwarf Fortress.

To Use

1. Install Dwarf Fortress and a current DFHack.
2. Download Armok Vision from the forum thread.
3. Load into a fortress mode map.
4. Start up Armok Vision.
5. Enjoy!

To Contribute

Want to help out? We love contributions!

Bugs

If you've run into any bugs: report them! (You'll need a github account.) Make sure to describe the issue in as much detail as you can, and to mention what system & Armok Vision version you're using. Also, check if what you're reporting has been reported before.

Artists

If you're an artist and want to contribute 3D models, sounds, concept art:

• There should be a folder called StreamingAssets somewhere around the armok vision executable (or inside, if you're on a mac.) If you edit the files inside and restart Armok Vision, it will use your modified assets. Be careful editing the .xml files, they're finnicky. You can post your edited resources in the forum thread and we can try to integrate them with the project.
• Alternatively, load things up in Unity and edit them there (see the following instructions).
• Check the issues; there may be something open about things that need prettifying.

Developers

If you know how to code and want to hack on the engine:

1. Install Unity 5. (We're using the Personal Edition, and either the classic installer or Unity Hub is fine.)
2. Non-Windows users: install the Git LFS extension if you haven't already (testable with git lfs version).
3. $ git clone --recurse-submodules --depth 1 https://github.com/JapaMala/armok-vision.git (or without --depth 1 if you want the full history, but it's pretty big).
4. Load the armok-vision folder in the Unity editor.
5. Run the Mytools->Build Material Collection menu item. This is required after a fresh pull from Git, as well as after changing any material files.
6. Hack around. Check out the issues to find things that need fixing / ideas that could be implemented.
7. Submit a pull request with your changes!

Financially

If you want to buy the lead programmer a snack, you can donate on his Patreon Page

Structural Notes

(Some short notes for anyone getting started with the codebase.)

• Armok Vision is an application built with the Unity engine. It connects to the remotefortressreader DFHack plugin over TCP and exchanges protobuf-formatted messages. (You don't need to be familiar with DFHack to work with Armok Vision.)
• On the Unity side, the submodule Assets/RemoteClientDF-Net contains the generated C# protobuf files, as well as classes for managing the network connection. The script Assets/Scripts/MapGen/DFConnection.cs runs the connection on a separate thread and exposes data collected from DF.
• The script that actually manages the onscreen map is Assets/Scripts/MapGen/GameMap.cs, which stores the GameObjects representing different map chunks. It calls the scripts in Assets/Scripts/MapGen/Meshing to build the actual meshes (on separate threads).
• Most assets - textures, 3d models, sprites, etc. - are loaded at runtime from Assets/StreamingAssets, which is copied directly to folder containing the generated app. The script that handles this is Assets/Scripts/MapGen/ContentLoader.cs.

There's a lot of other stuff but hopefully it'll be reasonably self-explanatory. Alternatively, you can ask in the forum thread, or the #dfhack IRC channel on freenode; somebody might be lurking who can help.

armok-vision's Issues

AV causes the Dwarf Fortress window to respond extremely slowly

Before starting AV, the Dwarf Fortress window responds immediately to keypresses (e.g. panning with arrow keys). But as soon as AV connects, Dwarf Fortress lags considerably, and now takes multiple seconds to respond to any keypress.

Is this related to the amount of communication between AV and DFHack? Does AV query the entire map every second? Is there a change API that AV could use, so it's only notified when the map geometry changes?

No structures rendered (floors, walls, etc) - OSX Sierra

Hello! I'm new to using Armok Vision so I may be doing something wrong but:

When I load up my game I have a giant gaping hole where everything should be! I see my dwarves and other bits floating in it but otherwise it is empty.

Thanks so much for your time!

Draw distance of sprites very low

Hi, may just be missing a setting here.

In my current adventure mode playthrough, character sprites only render if they're within about 10 tiles of the camera's position in Armok Vision. I haven't tested in Fortress mode.

The sprites are within vision range of the adventurer. Terrain and such loads in fine.

I know there's a final option down at the end of the settings toolbar on the left, but it is blocked by the bottom toolbar being in front of it.

Thanks.

Anthill Mode

As suggested here on reddit, we could make a mode for looking underground that makes the ground transparent and the open space not, or something along those lines, to help with understanding tunnels & things.

High memory usage with low responsiveness

Armok Vision uses over 7 GB of memory after enabling FPS mode and walking around a small map.

This seems excessive, considering barely any of the world is rendered except a few layers. Contrast this with tile-based games like Minecraft which render similar numbers of tiles using much less memory and with more responsiveness.

Esc menu is difficult to use from FPS mode.

It's almost impossible to adjust any of the settings in the Esc menu from FPS mode. The menu appears, but the game randomly shows & hides the mouse, including when you try to click a slider, or release a slider. Plus the camera is still tracking the mouse when you're dragging a slider. It's also difficult to close the menu, since clicking elsewhere or pressing Esc often fails to close it.

Improve VR support

Because how cool would it be to play DF in full VR? (note: issue intended mostly as my own notes to learn a bit of Unity) Likely to use https://github.com/thestonefox/SteamVR_Unity_Toolkit for improved controller support.

Index Array Out Of Range causing DFConnection.Start() to fail

I haven't had much time to look into the exact reason, however:

PlantTokenList.cs line 73 is throwing an Array Index Out of Range for ColorTable on my system.
(Called from InitStatics, I lost my debug information for the call stack, I could be bothered to get it if necessary)

If this happens, then DFConnection.Start() will never complete its call and you'll be left staring at a blank canvas because connectionManager will still be a null reference.

May I recommend some sanity checking coded within DFConnection.Update()? That or you could consider putting the connectionManager initialization into DFConnection.Awake() to ensure that it'll always be called separate from the code that could possibly cause an exception

Enhancement idea: Support multiple languages.

Dwarf Fortress can't be translated. But if you can control it from Armok Vision then translating Armok Vision into multiple languages can be good idea. @JapaMala What do you think of it? PS. Sorry about my bad English.

Proper VR support.

There was an issue about this already, which has been closed, but this is more about planning how it will be implemented.

Two things need to be decided:

How will it be enabled? Should it be automatic as long as a headset is connected, or should a hotkey switch to VR mode, while the default remains 2D?

How to handle third person mode? I'm picturing having the currently working level around chest height, for standing mode, or desk height for sitting mode. And while there's plenty of ways of doing movement in first person, how will things be handles in third person?

Designate from Armok Vision

It would be totally rad if you could select areas and then designate them from Armok Vision. If we do designations, zones, and buildings, that's a large chunk of Fortress Mode playable from Unity, and it'll hopefully be reasonably straightforward to implement. Of course, it also opens the doors to loads and loads of bugs and complexities and issues; the biggest challenge would be avoiding accidentally violating DFs invariants.

Main DF window appears in glitched God Mode, never goes away

Occasionally, the game glitches & the main Dwarf Fortress window (i.e. the dwarfort.exe one) is drawn inside Armok Vision as one of the bounds of the area in God Mode.

Moreover, when the game glitches like this, none of the HUD controls work (i.e. attempting to show the minimap, the keyboard help, or the Esc menu all fail), except the toggle between this glitched God Mode & first person mode.

Armok Vision must be restarted.

Inconsistent slash direction in xml file loading paths

Steps to reproduce:

1. Open armok vision
2. While it is loading the xml files look at the slashes
3. The last two slashes are backslashes whereas all the other ones are forward
   Result:
   (user directory is the empty one. actually user directory name hidden for privacy purposes)

Hangs on startup (displaying blue screen) if DF is not running

May be wine-specific

Ramps don't update when new tile data is added.

If a ramp is generated on the edge of a map block, it won't respect the wall on the side that is loaded after it. The solution would be to regen the surrounding geometry once a block is pulled from DF.

Make MapTile a struct

Seeing as hundreds of millions of them are allocated, it's probably a good idea to allocate them all at once. (It will use marginally more memory, but still only like a megabyte, and put less stress on the GC.)

Moving the camera

right now the link between AV's camera and DF's is broken, with no other way to move the camera around properly.

functionality I think we need:

• Moving camera around with the keyboard (Just use default unity bindings for this)
• Make sure the loaded area is following the camera center
• Make following the DF screen still an option (This is mainly useful for initial camera setup)
• (Possibly) doubleclick to center the view onto a block.

Coordinate systems?

I'm trying to implement block selection in Unity and I'm running into some issues figuring out how to translate between Unity coordinates and Dwarf Fortress coordinates. I was wondering if we could document some things in GameMap.
Specific questions:

• What would a function mapping from a location in Unity-space to a map tile/block GameMap index look like? (specifically, to the coordinates of the 8 corners of the block?)
• What coordinate does DFtoUnityCoordinate return, relative to the cube that is a block (in the center of the top, I think?)
• How do the Unity origin and the Dwarf Fortress origin relate to each other?

How to load into fortress mode map?

HOw to load into fortress mode map????????????????????????????????

Improve terrain textures

How the game is rendering right now is good, but I think the game would benefit a lot from a proper texture design that smooths the borders between tiles of different type/color

Enhancement idea: Only show discovered tiles

Just an idea here. I have a fortress I'm working on, but I don't want to spoil what's inside the layers of rock I haven't dug into yet. It would be nice if there was a "spoiler" mode that would show everything (enabled by default), and I could disable that to only show what I can see or have built thus far.

Issue with transferred saved games

Loading up DF 0.43.05 64bit with LNP 0.43.05-r08 and Armok Vision 0.17.0.

Armok Vision loads up a map perfectly fine with any world generated on my machine. But when I try to load up a recently available world from a YouTuber, I get the following error.

The Google Analytic issue is probably Pihole, but the TLS issue is only present when loading the downloaded save file. The game run perfectly fine otherwise, so the world works in DF. Its known that the YouTuber does not use DFHack in his series, so that might be a point of failure.

Let me know if you need any more information from me, and thank you for your work on this!

Config.json not read in 0.9.1 release

Since I am still using the 0.40.24 release of dwarf fortress with dfhack 0.40.24-r5, I first tried armok-vision 0.9.0. After playing around a bit I noticed the Config.json, and tweaked the values for the following:

• drawRangeSide
• drawRangeUp
• drawRangeDown

I thought I would try 0.9.1 since I was missing tree foliage, but noticed Config.json was not included in the zip? I created the file anyway but changing the values for the above properties has no impact. I have not tested any other configuration options other than the above.

My next step is to update dwarf fortress and dfhack, and retest (since the foliage was still missing and I should blatantly be using the latest version of dfhack!), but since Config.json was not included in the 0.9.1 release I wondered whether its support might have been removed intentionally?

I will update this ticket once I have tested with the correct version of dfhack, my current setup is everything running in an ubuntu docker container, so I am using the linux 32bit version of armok-vision.

BTW really cool project, I am really excited to play with it more with my fort in progress!

linux_exe in manifest.json needs updated

Not a big deal at all, as I can use sed to fix manifest.json in my pack's build script, but thought you should know about it.

Improved documentation and user experience

Armok Vision would be even better with more documentation, and preferably some user feedback after launch.

In program:

• Show help text instead of handing when
  • AV is running but DF is not
  • the remotefortressreader version is old or too old
  • etc?

Other docs:

• Document all keybindings, preferably in an editable config file
• User manual
  • How to install
  • Available modes (overview, first person, DF-screen, etc)
  • Basic walkthrough
  • VR support and how to use it
  • Available settings
• Contributor guide
  • code
  • art

These docs should also be included in the release package.

Some Z-layers are never rendered in FPS mode.

When switching to FPS mode on a certain layer, then moving up or down a layer, some Z-layers are never rendered. Notice here, multiple tree layers aren't shown:

Some assets not loading?

Having some difficulty getting AV to show my meshes... At first I thought there was a problem with having replaced the StreamingAssets folder from the release installation I have of AV with a checkout of my fork, but as you can see both a bed and a door do appear with their meshes. Then I thought it might be that the nest box I created has some error which prevents it from loading (it shows up as a flat hexagon shape instead) - but a stock weapon stand also fails to load (shows as a flat screw press).

Immediately dies on Mac.Yosemite, probably due to custom content?

Ahoy. This may be a known thing for you, or something you shouldn't even have to worry about, but I thought I'd make contact just it case it WAS of interest. But I tried this out recently with 0.4 and could not get it to start. However, my current game has custom raws... a few new animals... a couple new stones (meteorite, jasper, etc.) If I had to guess I'd say this was just because you can't possibly code well for what people MIGHT do to their raws.

[Improvement] Show the current, min and max Z-levels that should be rendered in view

~Edit:

In my original post below, I was asking if there was a bug or the bug I thought was a feature.

It turns out neither.

The improvement here is simply showing which slices of Z-levels are supposed to be rendered in-to view as well as the CURRENT Z-level. Without this feedback, I am lost in space.

Regarding my question below:

This wasn't an issue or a bug, because the engine was rendering multiple Z-levels all the time. It's just that it takes much more time to render above-ground than the ground-level. Waiting up 3-4 mins or so, I did have the upper-levels rendered.

The strange thing though: This 3-4 mins is significantly shorter when a greater quality is chosen at startup. The FPS is lower of course, but the engine renders above-ground much sooner. I have made all my tests in Fastest mode, so this raised up this question. I became aware of this issue, when I changed to First Person Mode, and ran around, and went on an elevation, and then saw the branches of trees etc.

---

So to sum up, I would really suggest displaying the current elevation level of the user, as well as the number of the min and max z-levels (e.g. current - rangeDown, current + rangeUp). That would both help the UI and debugging

My original Post

I may be wrong, and this may not be an issue but may be a feature, yet I have to ask and point this out:

As you see in the screenshots below, only a single (actually, 2) level of Z-level is rendered in my view. Is there a configuration where the vertical depth is rendered as full? In youtube videos I see trees, houses etc. all reside over multiple Z-levels. In mine, I cant seem to toggle between the views below and the full-depth-z-level view.

Is this a bug? Or am I missing some configuration in DwarfFortess or ArmokVision?

Stuck in an infinite loop if DF crashes.

Pretty much what it says. Unity stops responding to anything, and has to be killed.

No key binding to show/hide the calendar/clock

It's somewhat difficult to click the calendar/clock tab, since Armok Vision hides the cursor on the second click. There should be a key binding for this.

IndexOutOfRangeException: Array index is out of range.

When I run Armok-Vision, the terrain is never rendered. And there is a message "IndexOutOfRangeException: Array index is out of range. "

Does this anything to do with my computer, like I forgot to install some files or else?

DF fails with SIGABRT if armok-vision connects with no map loaded

OS X 10.10, dfhack/develop.

Armok Vision 'Job failed to exec' for 'weird reason': 13

I'm trying Armok Vision with DFHack 0.43.05-beta-2 on Mac OS 10.9.5

The Armok Vision app pops [up on the toolbar] for an instant [barely perceptible actually; the surrounding icons just 'jiggle'] when I try to run it, then it vanishes again.

Nothing at all in the Unity log file. In fact I've been scouring the logs to find anything at all.

Eventually I came across the following in system.log:

May 4 00:21:20 Melanie-Smith-Rawlingss-iMac com.apple.launchd.peruser.501[154] (unity.GopalGraphics.Armok Vision.303632[1464]): Job failed to exec(3) for weird reason: 13
May 4 00:21:20 Melanie-Smith-Rawlingss-iMac.local Finder[180]: 8837325: Attempting to SIGCONT to pid #1464 failed, with errno=#3, or the process failed to actually start
May 4 00:21:20 Melanie-Smith-Rawlingss-iMac.local loginwindow[42]: ERROR | -[Application setAppContext:] | Unable to get PID for context [0,290887]
May 4 00:21:20 Melanie-Smith-Rawlingss-iMac.local Dock[178]: no information back from LS about running process LSASN:{hi=0x0;lo=0x47047}
May 4 00:21:20 Melanie-Smith-Rawlingss-iMac.local Finder[180]: 8837325: Attempting to SIGCONT to pid #1464 failed, with errno=#3, or the process failed to actually start
May 4 00:21:50 --- last message repeated 98 times ---
May 4 00:22:01 Melanie-Smith-Rawlingss-iMac.local ipcserver[1470]: Valve Steam ipcserver started: 1.04

That's all I've found. At the time I had DFhack running with a fortress open, per the Armok Vision instructions. But I get the same behaviour (and the same 'weird reason' error) if I try to run Armok Vision when DFHack isn't running at all. So I'm guessing Armok Vision cannot tell there's a DF game for it to talk to??

Possible to fall through nearby region tiles

In FPS mode, walking to the border of the map and attempting to jump onto a neighboring region causes one to fall off the world. The neighboring region tiles' floors, though contiguous with the map, appear to have no collision properties.

OS X standalone build broken

The OS X build of v0.3 displays nothing but a grey screen and "New Text". @kazimuth reports that it only works in the editor on his machine - a newly-built standalone build displays the same problem.

Armok Vision not running in Ubuntu because of case sensitive names

Platform: Ubuntu 64 bits.
Downloaded from github. Started, nothing happens, only a blank screen, no map showed nor blocks received from DF.
After checking the log file in
/home/.config/unity3d/DefaultCompany/Armok Vision/Player.log
It was found that the problem was the asset WindMill.obj that needs to be renamed to Windmill.obj.

After renaming the asset. Armok Vision works ok

Secrets of the Beehive

I've made a beehive for Armok, single mesh, 470 tris, 261 verts - could this be a suitable object for inclusion?

If so, can you explain how texturing works in Armok - I expect the texture changes depending on the material the item is made from? Does that mean the object only has a single texture, or can this somehow be specified in the UV/other maps?

Talk to DF with a background thread

I'm doing a little profiling, and currently the call to RemoteClient.suspend_game() from GameMap.Update() is taking up 6-25ms most frames. GameMap.GetBlockList() also takes 2-3ms.

Running these on a background thread could speed up the main thread a lot. Any results could be put into a queue to be processed by the main thread, so that it doesn't have to wait.

It might even be possible to compute meshes on a background thread, at least the vertices / edges for the blocky parts of the world - it wouldn't be possible to copy existing meshes, though, because no Unity API in other threads.

Ceilings below unexcavated tiles are rendered in blue

I have a schist room, with a chert cavern above it. In the lower room, ceiling tiles that correspond to visible chert tiles are rendered correctly (as grey stone). Ceiling tiles below unexcavated tiles on the chert level are rendered as blue, which is somewhat of an eyesore.

Armok Vision doesn't have to cheat and reveal what the unexcavated floor tiles are, although it arguably should, since those tiles would be visible from below, but it could at least guess the composition from nearby tiles and avoid making half the ceiling bright blue.

Pool Protobuf objects

We're currently using ~30kb of Protobuf every frame - and that's when no tile data is coming in. It'll probably eventually be a good idea to implement object pooling to keep allocation down.

Falling out of world in FPS mode

It's very easy to confuse armok vision and fall out of the world. I was descending my central staircase in FPS mode and got well below where Armok Vision had rendered, then I started falling.

Also, very often when switching to FPS mode, the camera is placed below the floor of wherever is visible in god mode, and consequently falls out of the world. Armok Vision should try to find a floor, even one several layers above where god mode is currently focused, before deciding to place the FPS camera under the ground and letting it fall into the void.

Distribute a manifest.json, for PyLNP

It would be great if a manifest for PyLNP could be included, along with the other ReleaseFiles. Here's what I'm using for Armok Vision:

{
"win_exe": "Armok Vision.exe",
"tooltip": "A full 3D visualiser - shows off Dwarf Fortress with unprecedented detail and beauty.",
"title": "Armok Vision",
"content_version": "v0.11.2",
"needs_dfhack": true
}

Ideally the version and *_exe properties would be set by your build scripts, so they would always stay up to date.

Mesher keeps meshing after the view has moved.

Pretty much what it says. The solution would be to always get the most needed block when it does a meshing, rather than have a fixed queue, or at least check if it's in the viewable area, and skip it if it's not, going directly to the next one.

Empty Starry Sky

When I launch Armok vision, all I see is a blank starry sky:

The only output logged to the console is:

Set current directory to /home/jghibiki/Downloads/Armok.Vision.v0.14.0.Linux
Found path: /home/jghibiki/Downloads/Armok.Vision.v0.14.0.Linux/Armok Vision.x86_64
Mono path[0] = '/home/jghibiki/Downloads/Armok.Vision.v0.14.0.Linux/Armok Vision_Data/Managed'
Mono path[1] = '/home/jghibiki/Downloads/Armok.Vision.v0.14.0.Linux/Armok Vision_Data/Mono'
Mono config path = '/home/jghibiki/Downloads/Armok.Vision.v0.14.0.Linux/Armok Vision_Data/Mono/etc'
displaymanager : xrandr version warning. 1.5
client has 4 screens
displaymanager screen (0)(LVDS1): 1600 x 900
Using libudev for joystick management


Importing game controller configs

I am running on arch linux with DFHack version 0.43.03-r1. I have tried every release of armok vision and the same result is produced by all.

The only keybindings that appear to work is right clicking to swivel the camera.

Thank you.

Floors/Blocks don't render when looking at them from below

When in first person, looking up at floors/blocks causes them to be transparent up to trees. Trees, Stairs, and objects are not affected by this bug.

Logo

It would be rad to have one!

Armok Vision exits silently on Ubuntu 64

I've got latest Armok Vision (0.15), latest DF (0.43.05) and latest DFHack (0.43.05-beta1 x86_64). DF lauches with DFHack and seems to run very well, but after loading up a fortress and subsequently launching AV it exits silently when I click the "Ok" button:

me@machine:~/ArmokVision$ ./Armok\ Vision.x86_64
Set current directory to /home/me/ArmokVision
Found path: /home/me/ArmokVision/Armok Vision.x86_64
Mono path[0] = '/home/me/ArmokVision/Armok Vision_Data/Managed'
Mono path[1] = '/home/me/ArmokVision/Armok Vision_Data/Mono'
Mono config path = '/home/me/ArmokVision/Armok Vision_Data/Mono/etc'
displaymanager : xrandr version warning. 1.5
displaymanager : trying .X11-unix
client :0 has 1 screens
displaymanager screen (0): 1280 x 800
Using libudev for joystick management


Importing game controller configs
me@machine:~/ArmokVision$ 

I haven't been able to find any logfiles or other clues to what the problem might be.

Sluggish

Is Armok Vision suppose to be very sluggish in following dwarf fortress? FPS wise Armok Vision is fast but following the DF screen there is a decent amount delay. If this isn't how it should be then I guess this post belongs here for now and if otherwise then I'll remove it, thank you.

Edit: It seems this only occurs on the latest version 17.1

Load textures at runtime

So that people can edit textures without having to rebuild the app.