Having digged a bit into the details of how the journal was ment wo work, I have gathered some information on how to add a custom view into Stonehearth (and link it to a command and an entity).
As I have just started to understand how the things are working together and for the sake of having this designed as an entry tutorial, the view we create will not be too complicated and only include one additional action, i.e. to close the window.
This time we will have to change more files than in the other tutorials so far⌠but there is nothing too complicated.
- Add a command in ââŚ\Stonehearth\mods\stonehearth\data\commandsâ
- Add a User Interface in ââŚ\Stonehearth\mods\stonehearth\ui\gameâ
- Add entries to the Manifest ââŚ\Stonehearth\mods\stonehearth\manifest.jsonâ
- Add command to entity(-ies) ââŚ\Stonehearth\mods\stonehearth\entitiesâ
So, letâs get our hands dirty and into itâŚ
** Create a new command**
You can see a command as the small icons which are visible once you have selected an entity in the world (e.g. a worker or a crafted item). In the folder ââŚ\Stonehearth\mods\stonehearth\data\commandsâ you will find the available commands and for this example we want to create a new one. Just copy & paste the âshow_journalâ-folder and rename it to something like âshow_infoâ. In this folder you will find 2 files, one picture and a .json-file. Rename also both of this files and rename 3 entries in the .json-file from âshow_journalâ to âshow_infoâ.
The .json-file simply defines the name of the command and the action which is called once the user clicks on the icon. Nothing too complicated so far.
** Define the view (User Interface)**
The folder ââŚ\Stonehearth\mods\stonehearth\ui\gameâ includes different elements which you will see as a User Interface in the game. We want to add here details about the look and functions of our custom view.
Go ahead and copy & paste the folder âshow_journalâ (which should also exist already in the game-folder) and rename it to âshow_infoâ. Inside the folder you will find another folder, which includes images. We want to add another image here which will be used to close the view. Just copy & paste the following into the image-folder:
ââŚ\Stonehearth\mods\stonehearth\ui\game\show_workshop\images\close_button.pngâ
Now there are three files in the âshow_infoâ-folder:
- âshow_info.lessâ (after you have renamed it)⌠is a css-file and contains formating information.
- âshow_info.htmlâ (after you have renamed it)⌠where you can also embed handlebars expressions (actions).
- âshow_info:jsâ (after you have renamed it)⌠which contains the âlogicâ.
If you have copy & pasted the âshow_journalâ-folder, you can adjust the css-file a bit to look like this:
#infoWindow {
position: absolute;
top: 100px;
left: 100px;
width: 424px;
height: 589px;
background: url('images/recipe_scroll.png');
}
#infoTitle {
margin-top: 30px;
margin-left: 80px;
margin-right: 80px;
text-align: center;
.controlFont;
font-size: 18px;
}
#infoEntries {
position: absolute;
width: 350px;
height: 460px;
overflow: auto;
margin: 30px;
font-size: 14px;
}
#closeButton {
position: absolute;
top: 30px;
right: 50px;
width: 25px;
height: 27px;
display: block;
background: url('./images/close_button.png');
}
As this is css, we are defining some design elements (window, title, etc.) and their size, location, etc.
Next you want to adjust the .html-file to look more like this:
<script type="text/x-handlebars" data-template-name="stonehearthInfo">
<div id="infoWindow">
<a id="closeButton" {{action hide target="view"}}></a>
<div id="infoTitle">Custom Text</div>
<div id="infoEntries">
Dog goes woof<br>
Cat goes meow<br>
Bird goes tweet<br>
and mouse goes squeek<p>
Cow goes moo<br>
Frog goes croak<br>
and the elephant goes toot<p>
Ducks say quack<br>
and fish go blub<br>
and the seal goes ow ow ow ow ow<p>
But theres one sound<br>
That no one knows<br>
What does the fox say?
</div>
</div>
</script>
You see that we are using the names for our design elements as defined in the .css-file. Other than that you will only see one âstrangeâ entry which is:
<a id="closeButton" {{action hide target="view"}}></a>
That is actually where we are embedding an expression from handlebars. We are defining a button which is linked to an action (to hide the view). Apart from that, plain html.
Finally we have the .js-file which we want to look like this:
$(document).ready(function(){
$(top).on('show_info.stonehearth', function (_, e) {
var view = App.gameView.addView(App.StonehearthInfoView, { uri: e.entity });
});
});
App.StonehearthInfoView = App.View.extend({
templateName: 'stonehearthInfo',
modal: true,
actions: {
hide: function() {
var self = this;
self.destroy()
}
}
});
This is a quite short-version of the .js-file if you compare it to others which you can find in the game-folder. It only adds a view to the game and links it to an action (closing the window).
** Introducing UI to manifest.json**
At the bottom of the file âââŚ\Stonehearth\mods\stonehearth\manifest.json"", you will find some entries linked to the UI. Actually you will find one section for the âhtmlâ, one for the âjsâ and one for the âlessâ-files. Just add the link to your files:
- âfile(ui/game/show_info/show_info.html)â,
- âfile(ui/game/show_info/show_info.js)â,
- âfile(ui/game/show_info/show_info.less)â,
If you are not sure where to add them, look for âshow_journalâ and add your links underneath the different entries you will find.
** Link command to entity**
We need to link our command to an entity which will allow us to trigger the related action (showing the view). Entities you will find in the folder ââŚ\Stonehearth\mods\stonehearth\entitiesâ and they are actually everything you can see in the world (more or less). So you will find here the craftable items, animals, monsters, workers, etc.
Not all entities are eligible to include all commands. E.g. the journal requires some data about the entity which is calling it (e.g. personality). Furniture might not have âpersonalityâ (letâs not discuss this now ), so this command will not work for furniture. Just play around a bit and try adding commands to different things (pay attention with the âdestroy_entityâ-command, it DOES work with workers .
For this example I have adjusted the âCamp Standardâ and opened the âcamp_standard.jsonâ which you can find here: ââŚ\Stonehearth\mods\stonehearth\entities\gizmos\camp_standardâ. This entity will not have any commands yet included. Just go ahead and add the following code somewhere inside the âcomponentsâ-brackets:
"stonehearth:commands" : {
"commands" : [
"file(/data/commands/show_info)"
]
},
If you restart the game now, you shoudl see an additional icon once you click on the Camp Standard. Once activated, a new view should become visible which you can either close by clicking again on the item, or using the cross on the top right.
The video (19 Min.) might clarify some open questions: