Modding:World Access: Difference between revisions
No edit summary |
m (Updated navbox to new code navbox.) |
||
(14 intermediate revisions by 6 users not shown) | |||
Line 1: | Line 1: | ||
== Get and Set Blocks through the API == | {{GameVersion|1.19.3}} | ||
<languages/> | |||
<translate> | |||
== Get and Set Blocks through the API == <!--T:3--> | |||
<!--T:4--> | |||
Let's Take our basic mod init code for a server mod | Let's Take our basic mod init code for a server mod | ||
<!--T:5--> | |||
<syntaxhighlight lang="c#"> | <syntaxhighlight lang="c#"> | ||
public class SampleMod : | public class SampleMod : ModSystem | ||
{ | { | ||
ICoreServerAPI api; | ICoreServerAPI api; | ||
public override bool ShouldLoad(EnumAppSide side) | <!--T:6--> | ||
public override bool ShouldLoad(EnumAppSide side) | |||
{ | { | ||
return side == EnumAppSide.Server; | return side == EnumAppSide.Server; | ||
Line 14: | Line 20: | ||
public override void StartServerSide(ICoreServerAPI api) | <!--T:7--> | ||
public override void StartServerSide(ICoreServerAPI api) | |||
{ | { | ||
this.api = api; | this.api = api; | ||
Line 21: | Line 28: | ||
</syntaxhighlight> | </syntaxhighlight> | ||
<!--T:8--> | |||
With this you can already start placing or reading blocks using the api object. Please note that mods are loaded before the world is loaded, so you cannot immediately access the world. Depending on what you want to achieve, you have to register to the appropriate event. For some examples in order to do something... | With this you can already start placing or reading blocks using the api object. Please note that mods are loaded before the world is loaded, so you cannot immediately access the world. Depending on what you want to achieve, you have to register to the appropriate event. For some examples in order to do something... | ||
* after the world has loaded you could register to the RunGame phase: <code>api.Event.ServerRunPhase(EnumServerRunPhase.RunGame, OnRunGame);</code> | * after the world has loaded you could register to the RunGame phase: <code>api.Event.ServerRunPhase(EnumServerRunPhase.RunGame, OnRunGame);</code> | ||
* during world generation we'd have to register to the [[WorldGen API|appropriate world gen events]]. | * during world generation we'd have to register to the [[WorldGen API|appropriate world gen events]]. | ||
* when the player runs a custom command we need to register one: <code>api.RegisterCommand("test", "a test command", "", OnCommand);</code> | * when the player runs a custom command we need to register one: <code>api.RegisterCommand("test", "a test command", "", OnCommand);</code> | ||
* when a player joins the game: <code>api.Event.PlayerJoin | * when a player joins the game: <code>api.Event.PlayerJoin += OnPlayerJoin;</code> | ||
<!--T:9--> | |||
Let's register to the player join event. | Let's register to the player join event. | ||
<!--T:10--> | |||
<syntaxhighlight lang="c#"> | <syntaxhighlight lang="c#"> | ||
public override void StartServerSide(ICoreServerAPI api) | public override void StartServerSide(ICoreServerAPI api) | ||
{ | { | ||
this.api = api; | this.api = api; | ||
api.Event.PlayerJoin | api.Event.PlayerJoin += OnPlayerJoin; | ||
} | } | ||
private void OnPlayerJoin(IServerPlayer byPlayer) | <!--T:11--> | ||
private void OnPlayerJoin(IServerPlayer byPlayer) | |||
{ | { | ||
Line 42: | Line 53: | ||
</syntaxhighlight> | </syntaxhighlight> | ||
<!--T:12--> | |||
Let's do 2 simple things whenever a player joins: | Let's do 2 simple things whenever a player joins: | ||
* Always place some fire clay bricks just below his feet | * Always place some fire clay bricks just below his feet | ||
* Count the amount log blocks around the player in a 3 block radius | * Count the amount log blocks around the player in a 3 block radius | ||
<!--T:13--> | |||
Now, blocks are always uniquely identified by a number of characters called the block code. If you want to find out a blocks code, a simple way of doing it is to start the game, enable the debug info mode via the command <code>.edi</code> and look at a block in the creative inventory: | Now, blocks are always uniquely identified by a number of characters called the block code. If you want to find out a blocks code, a simple way of doing it is to start the game, enable the debug info mode via the command <code>.edi</code> and look at a block in the creative inventory: | ||
<!--T:14--> | |||
[[File:Blockcode.png]] | [[File:Blockcode.png]] | ||
<!--T:15--> | |||
So the code of a fire brick block is game:claybricks-fire. The first part before the colon is the domain, for the default domain 'game' we can usually ignore it. | So the code of a fire brick block is game:claybricks-fire. The first part before the colon is the domain, for the default domain 'game' we can usually ignore it. | ||
<!--T:16--> | |||
We now have to retrieve it's number identifier for this particular world in order to get or set it. We do this as followed: | We now have to retrieve it's number identifier for this particular world in order to get or set it. We do this as followed: | ||
<!--T:17--> | |||
<syntaxhighlight lang="c#"> | <syntaxhighlight lang="c#"> | ||
private void OnPlayerJoin(IServerPlayer byPlayer) | private void OnPlayerJoin(IServerPlayer byPlayer) | ||
{ | { | ||
Block firebrickblock = api.World.GetBlock(new AssetLocation("claybricks-fire")); | Block firebrickblock = api.World.GetBlock(new AssetLocation("claybricks-fire")); | ||
int blockId = firebrickblock.BlockId; | |||
} | } | ||
</syntaxhighlight> | </syntaxhighlight> | ||
<!--T:18--> | |||
Now all we have to do is set the block right below the players position through the IBlockAccessor interface. | Now all we have to do is set the block right below the players position through the IBlockAccessor interface. | ||
<!--T:19--> | |||
<syntaxhighlight lang="c#"> | <syntaxhighlight lang="c#"> | ||
BlockPos plrpos = byPlayer.Entity.Pos.AsBlockPos; | BlockPos plrpos = byPlayer.Entity.Pos.AsBlockPos; | ||
Line 69: | Line 88: | ||
</syntaxhighlight> | </syntaxhighlight> | ||
<!--T:20--> | |||
We're using <code>plrpos.DownCopy()</code> to keep the original player position for later use and to move the position down by 1 for placing the block below the player. | We're using <code>plrpos.DownCopy()</code> to keep the original player position for later use and to move the position down by 1 for placing the block below the player. | ||
<!--T:21--> | |||
And finally let's count the number of log blocks around the player and inform him via chat message. | And finally let's count the number of log blocks around the player and inform him via chat message. | ||
<!--T:22--> | |||
<syntaxhighlight lang="c#"> | <syntaxhighlight lang="c#"> | ||
// Check a | // Check a 7x7x7 area for logs | ||
int quantityLogs = 0; | int quantityLogs = 0; | ||
for (int x = -3; x <= 3; x++) | for (int x = -3; x <= 3; x++) | ||
Line 82: | Line 104: | ||
for (int z = -3; z <= 3; z++) | for (int z = -3; z <= 3; z++) | ||
{ | { | ||
Block block = api.World.BlockAccessor.GetBlock(plrpos.X + x, plrpos.Y + y, plrpos.Z + z); | Block block = api.World.BlockAccessor.GetBlock(new BlockPos(plrpos.X + x, plrpos.Y + y, plrpos.Z + z, plrpos.dimension)); | ||
if (block.Code.Path.Contains("log")) | if (block.Code.Path.Contains("log")) | ||
{ | { | ||
Line 96: | Line 118: | ||
<!--T:25--> | |||
Alternatively we could also use a shorthand method to have more elegant code. | Alternatively we could also use a shorthand method to have more elegant code. | ||
<!--T:26--> | |||
<syntaxhighlight lang="c#"> | <syntaxhighlight lang="c#"> | ||
int quantityLogs = 0; | int quantityLogs = 0; | ||
Line 103: | Line 127: | ||
plrpos.AddCopy(-3, -3, -3), | plrpos.AddCopy(-3, -3, -3), | ||
plrpos.AddCopy(3, 3, 3), | plrpos.AddCopy(3, 3, 3), | ||
(block, | (block, x, y, z) => quantityLogs += block.Code.Path.Contains("log") ? 1 : 0 | ||
); | ); | ||
byPlayer.SendMessage(GlobalConstants.GeneralChatGroup, "You have " + quantityLogs + " logs nearby you", EnumChatType.Notification); | <!--T:27--> | ||
byPlayer.SendMessage(GlobalConstants.GeneralChatGroup, "You have " + quantityLogs + " logs nearby you", EnumChatType.Notification); | |||
</syntaxhighlight> | </syntaxhighlight> | ||
<!--T:28--> | |||
And the complete code and final result: | And the complete code and final result: | ||
<!--T:29--> | |||
<syntaxhighlight lang="c#"> | <syntaxhighlight lang="c#"> | ||
private void OnPlayerJoin(IServerPlayer byPlayer) | private void OnPlayerJoin(IServerPlayer byPlayer) | ||
{ | { | ||
Block firebrickblock = api.World.GetBlock(new AssetLocation("claybricks-fire")); | |||
int blockId = firebrickblock.BlockId; | |||
BlockPos plrpos = byPlayer.Entity.Pos.AsBlockPos; | BlockPos plrpos = byPlayer.Entity.Pos.AsBlockPos; | ||
api.World.BlockAccessor.SetBlock(blockId, plrpos.DownCopy()); | api.World.BlockAccessor.SetBlock(blockId, plrpos.DownCopy()); | ||
// Check a | // Check a 7x7x7 area for logs | ||
int quantityLogs = 0; | int quantityLogs = 0; | ||
api.World.BlockAccessor.WalkBlocks( | api.World.BlockAccessor.WalkBlocks( | ||
plrpos.AddCopy(-3, -3, -3), | plrpos.AddCopy(-3, -3, -3), | ||
plrpos.AddCopy(3, 3, 3), | plrpos.AddCopy(3, 3, 3), | ||
(block, | (block, x, y, z) => quantityLogs += block.Code.Path.Contains("log") ? 1 : 0 | ||
); | ); | ||
byPlayer.SendMessage(GlobalConstants.GeneralChatGroup, "You have " + quantityLogs + " logs nearby you", EnumChatType.Notification); | byPlayer.SendMessage(GlobalConstants.GeneralChatGroup, "You have " + quantityLogs + " logs nearby you", EnumChatType.Notification); | ||
} | } | ||
</syntaxhighlight> | </syntaxhighlight> | ||
<!--T:33--> | |||
[[File:SetblockTut.png|500px]] | [[File:SetblockTut.png|500px]] | ||
<!--T:34--> | |||
I hope this taught you the basics of accessing the world. More ways to access blocks and entities will be added here in the future. | I hope this taught you the basics of accessing the world. More ways to access blocks and entities will be added here in the future. | ||
</translate> | |||
{{Navbox/codemodding}} | |||
{{Navbox/ |
Latest revision as of 17:03, 27 March 2024
This page was last verified for Vintage Story version 1.19.3.
Get and Set Blocks through the API
Let's Take our basic mod init code for a server mod
public class SampleMod : ModSystem
{
ICoreServerAPI api;
public override bool ShouldLoad(EnumAppSide side)
{
return side == EnumAppSide.Server;
}
public override void StartServerSide(ICoreServerAPI api)
{
this.api = api;
}
}
With this you can already start placing or reading blocks using the api object. Please note that mods are loaded before the world is loaded, so you cannot immediately access the world. Depending on what you want to achieve, you have to register to the appropriate event. For some examples in order to do something...
- after the world has loaded you could register to the RunGame phase:
api.Event.ServerRunPhase(EnumServerRunPhase.RunGame, OnRunGame);
- during world generation we'd have to register to the appropriate world gen events.
- when the player runs a custom command we need to register one:
api.RegisterCommand("test", "a test command", "", OnCommand);
- when a player joins the game:
api.Event.PlayerJoin += OnPlayerJoin;
Let's register to the player join event.
public override void StartServerSide(ICoreServerAPI api)
{
this.api = api;
api.Event.PlayerJoin += OnPlayerJoin;
}
private void OnPlayerJoin(IServerPlayer byPlayer)
{
}
Let's do 2 simple things whenever a player joins:
- Always place some fire clay bricks just below his feet
- Count the amount log blocks around the player in a 3 block radius
Now, blocks are always uniquely identified by a number of characters called the block code. If you want to find out a blocks code, a simple way of doing it is to start the game, enable the debug info mode via the command .edi
and look at a block in the creative inventory:
So the code of a fire brick block is game:claybricks-fire. The first part before the colon is the domain, for the default domain 'game' we can usually ignore it.
We now have to retrieve it's number identifier for this particular world in order to get or set it. We do this as followed:
private void OnPlayerJoin(IServerPlayer byPlayer)
{
Block firebrickblock = api.World.GetBlock(new AssetLocation("claybricks-fire"));
int blockId = firebrickblock.BlockId;
}
Now all we have to do is set the block right below the players position through the IBlockAccessor interface.
BlockPos plrpos = byPlayer.Entity.Pos.AsBlockPos;
api.World.BlockAccessor.SetBlock(blockId, plrpos.DownCopy());
We're using plrpos.DownCopy()
to keep the original player position for later use and to move the position down by 1 for placing the block below the player.
And finally let's count the number of log blocks around the player and inform him via chat message.
// Check a 7x7x7 area for logs
int quantityLogs = 0;
for (int x = -3; x <= 3; x++)
{
for (int y = -3; y <= 3; y++)
{
for (int z = -3; z <= 3; z++)
{
Block block = api.World.BlockAccessor.GetBlock(new BlockPos(plrpos.X + x, plrpos.Y + y, plrpos.Z + z, plrpos.dimension));
if (block.Code.Path.Contains("log"))
{
quantityLogs++;
}
}
}
}
byPlayer.SendMessage(GlobalConstants.GeneralChatGroup, "You have " + quantityLogs + " logs nearby you", EnumChatType.Notification);
Alternatively we could also use a shorthand method to have more elegant code.
int quantityLogs = 0;
api.World.BlockAccessor.WalkBlocks(
plrpos.AddCopy(-3, -3, -3),
plrpos.AddCopy(3, 3, 3),
(block, x, y, z) => quantityLogs += block.Code.Path.Contains("log") ? 1 : 0
);
byPlayer.SendMessage(GlobalConstants.GeneralChatGroup, "You have " + quantityLogs + " logs nearby you", EnumChatType.Notification);
And the complete code and final result:
private void OnPlayerJoin(IServerPlayer byPlayer)
{
Block firebrickblock = api.World.GetBlock(new AssetLocation("claybricks-fire"));
int blockId = firebrickblock.BlockId;
BlockPos plrpos = byPlayer.Entity.Pos.AsBlockPos;
api.World.BlockAccessor.SetBlock(blockId, plrpos.DownCopy());
// Check a 7x7x7 area for logs
int quantityLogs = 0;
api.World.BlockAccessor.WalkBlocks(
plrpos.AddCopy(-3, -3, -3),
plrpos.AddCopy(3, 3, 3),
(block, x, y, z) => quantityLogs += block.Code.Path.Contains("log") ? 1 : 0
);
byPlayer.SendMessage(GlobalConstants.GeneralChatGroup, "You have " + quantityLogs + " logs nearby you", EnumChatType.Notification);
}
I hope this taught you the basics of accessing the world. More ways to access blocks and entities will be added here in the future.
Code Modding | |||||||
---|---|---|---|---|---|---|---|
Basics | Code Mods • Preparing For Code Mods • Creating A Code Mod | ||||||
Tutorials |
|
||||||
Advanced | Server-Client Considerations • Setting up your Development Environment • Advanced Blocks • Advanced Items • Block and Item Interactions • Block Behavior • Block Entity • Particle Effects • World Access • Inventory Handling • Commands • GUIs • Network API • Monkey patching (Harmony) | ||||||
Data Management | Savegame Data Storage • ModConfig File • Chunk Data Storage • TreeAttribute | ||||||
Worldgen | WorldGen API • NatFloat • EvolvingNatFloat | ||||||
Rendering | Shaders and Renderers |
Wondering where some links have gone?
The modding navbox is going through some changes! Check out Navigation Box Updates for more info and help finding specific pages.
Modding | |
---|---|
Modding Introduction | Getting Started • Theme Pack |
Content Modding | Content Mods • Developing a Content Mod • Basic Tutorials • Intermediate Tutorials • Advanced Tutorials • Content Mod Concepts |
Code Modding | Code Mods • Setting up your Development Environment |
Property Overview | Item • Entity • Block • Block Behaviors • Block Classes • Block Entities • Block Entity Behaviors • World properties |
Workflows & Infrastructure | Modding Efficiency Tips • Mod-engine compatibility • Mod Extensibility • VS Engine |
Additional Resources | Community Resources • Modding API Updates • Programming Languages • List of server commands • List of client commands • Client startup parameters • Server startup parameters Example Mods • API Docs • GitHub Repository |