Modding: Item Simples do Tutorial de Código
Esta página foi verificada pela última vez para a versão do Vintage Story 1.20.3.
Introdução
Objetivo
Neste tutorial, você criará um item com funcionalidade personalizada básica. Você descobrirá como as classes de itens são registradas e como interagir ainda mais com as entidades. O item que você criará é uma nova espada ‘espinhosa’, que machucará levemente o jogador quando usada para atacar.
Pré-requisitos
Recomenda-se usar o mesmo projeto para todos os tutoriais de código mais recentes, com o nome de projeto "VSTutorial". Se você ainda não fez isso, siga os seguintes tutoriais:
Este tutorial também pressupõe que você leu:
Também é altamente recomendável ter concluído o tutorial anterior da série de códigos:
Ativos
Este tutorial usa o projeto finalizado do tutorial anterior. Se precisar, você pode baixar a versão final do tutorial anterior no GitHub aqui.
Como sempre, você precisa dos recursos necessários para este tutorial. Eles podem ser baixados do GitHub aqui e devem substituir toda a sua pasta de ativos, pois ela também contém os ativos do tutorial anterior. Quando esses arquivos forem adicionados, você deverá ter novos arquivos de tipo de item, forma e textura.
Execute o jogo, inicie um mundo e verifique o menu criativo. Você deve conseguir encontrar a "Lâmina de Espinhos".
| Jogando Vintage Story em modo tela cheia? |
| É altamente recomendado rodar o jogo em modo janela ao fazer mods de código. Se o seu código resultar em erro, o Visual Studio tentará obter foco e o Vintage Story irá parar de responder. Você pode pressionar F11 para alternar facilmente entre os modos de tela inteira e janela. |
Classe do item
Feche o jogo e volte para o Visual Studio. Para adicionar funcionalidade personalizada ao item, você precisará criar uma classe de item.
Uma classe de item é um script que oferece funcionalidade personalizada para qualquer ativo de tipo de item específico. Observe que cada tipo de item só pode ter uma única classe de item anexada.
Criar uma classe de item é extremamente semelhante à criação de uma classe de bloco.
Criando uma classe de item
Para manter o código organizado, você deve criar uma nova pasta chamada “Itens”. Clique com o botão direito no seu projeto, passe o mouse sobre adicionar e selecione Nova Pasta.
Você também precisa de um nome para a nova classe de item. Eles seguem a mesma convenção dos Blocos e da maioria dos outros tipos. Neste caso, nossa classe de item de lâmina espinhosa, você deve nomear esta classe como "ItemThornsBlade".
Crie sua nova classe. Clique com o botão direito na nova pasta, passe o mouse sobre Adicionar e selecione Classe. Certifique-se de ter a Classe padrão selecionada na lista de modelos, insira o nome da sua turma e clique em criar.
A classe que você criou precisa estender a classe ‘Item’. Isso permitirá que você use muitas das funções disponíveis para itens. Altere a definição da classe para agora:
internal class ItemThornsBlade : Item
Na maioria das vezes, o Visual Studio adicionará automaticamente instruções 'using'. Porém, se houver erro, clique em "Item", pressione Alt+Enter e selecione a opção "usando Vintagestory.API.Common".
A classe ItemThornsBlade agora existe, mas não faz nada. É hora de substituir uma função, suponho.
Dentro da classe vazia, digite “override” e uma lista de métodos que podemos usar será exibida. Neste caso, você desejará substituir a função 'OnAttackingWith'. Esta função é chamada sempre que nosso item é usado para atacar uma entidade. Pesquise isso na lista e clique duas vezes nele para adicionar automaticamente o exemplo de código necessário.
Sua classe agora deve ficar assim:
| ItemThornsBlade.cs |
usando Vintagestory.API.Common;
usando Vintagestory.API.Common.Entities;
namespace VSTutorial.Items
{
classe interna ItemThornsBlade: Item
{
substituição pública void OnAttackingWith (IWorldAccessor world, Entity byEntity, Entity attackEntity, ItemSlot itemslot)
{
base.OnAttackingWith(mundo, byEntity, attackEntity, itemslot);
}
}
}
|
Observe que o código de exemplo em 'OnAttackingWith' contém uma função chamada 'base.OnAttackingWith'. Isso essencialmente executa qualquer comportamento padrão para a função. Se você removesse esta linha, nenhum comportamento padrão aconteceria e, neste caso, o item não perderia durabilidade quando usado para atacar.
Na função OnAttackingWith, você tem acesso ao mundo, à entidade que está atacando, à entidade que está sendo atacada e ao slot de item em que esse item existe. Para fins de teste, adicione algum código que envie uma mensagem para o console quando atacamos uma entidade. Você precisará adicionar o seguinte código abaixo da linha 'base':
world.Api.Logger.Event("Got attack with thorns blade!");Você pode acessar a API do jogo atual de vários lugares. Esta linha específica acessa a API através do mundo, porém também pode ser acessada através de qualquer entidade com código muito semelhante. Você deve estar ciente de que isso criará uma mensagem no console quando atacarmos uma entidade com o novo item.
Cadastrando a Classe do Item
A classe para a lâmina de espinhos é criada, porém antes de poder ser utilizada ela precisa ser cadastrada através da API do jogo. No seu sistema mod, que você usou no tutorial anterior, você precisa registrar uma classe de item para o cliente e para o servidor.
Na função Start, faça uma chamada para a função RegisterItemClass na API. Adicione o seguinte código em uma nova linha dentro do bloco da função Iniciar:
api.RegisterItemClass();
Semelhante ao tutorial anterior, isso resultará em um erro. Você precisará adicionar alguns parâmetros à função. Não se esqueça, você pode passar o mouse sobre a função e os parâmetros necessários serão mostrados. Neste caso, mais uma vez precisamos de um nome de classe e de um tipo. O argumento do nome da sua classe deve estar totalmente em letras minúsculas e geralmente deve ser o ID do seu mod, unido ao nome da classe que você acabou de criar. O itemType será a classe que você acabou de criar. Substitua a função pelo seguinte:
api.RegisterItemClass(Mod.Info.ModID + ".thornsblade", typeof(ItemThornsBlade));
Isso registrará a classe ItemThornsBlade com o nome "vstutorial.thornsblade".
| Por que incluir o ID do mod aqui? |
| Se você criou mods de código antes da introdução desses novos tutoriais, provavelmente não incluiu seu ID de mod ao registrar aulas. À medida que mais e mais mods são feitos, há colisões ocasionais em relação aos nomes das classes. Digamos, por exemplo, que dois mods adicionem uma classe de bloco 'trampolim'. Existirá apenas uma instância da classe trampolim, o que pode causar problemas se tiverem funcionalidades ligeiramente diferentes.
Portanto, incluir seu ID de mod ao registrar aulas garantirá que essas ‘colisões’ não ocorram. |
Adicionando classe de item ao ativo
Antes que seu item funcione, você precisa adicionar a classe ao arquivo de ativos. Abra o arquivo em assets/vstutorial/itemtypes/thornsblade.json.
Você precisa adicionar a seguinte propriedade ao arquivo:
"class": "vstutorial.thornsblade",
Geralmente, este elemento é colocado como a segunda propriedade em seu arquivo json, imediatamente abaixo da propriedade code.
Observe que o valor desta propriedade é idêntico ao valor que usamos na função RegisterItemClass. É assim que o jogo vincula os arquivos de ativos JSON às classes registradas do seu código.
Testando a classe do item
Pressione F5 novamente para iniciar o jogo com o mod. Lembre-se de definir o jogo para modo de janela pressionando F11. Encontre a lâmina de espinhos no menu criativo e use-a para atacar uma entidade. Após fazer isso, dê uma olhada no console que abriu ao iniciar o jogo. Você deverá conseguir ver os seguintes registros:
[Client Event] Got attack with thorns blade! [Server Event] Got attack with thorns blade!
Lembra do que está acontecendo aqui? Embora você tenha atacado a entidade apenas uma vez, existem duas entradas. Um deles é enviado ao console pelo cliente e o outro é enviado pelo servidor. Você deve começar a perceber que muito do código que você escreve acontecerá tanto no cliente quanto no servidor. Você verá maneiras de controlar isso mais tarde.
A classe e função da lâmina de espinhos estão funcionando, então feche o jogo e volte para a classe ItemThornsBlade.
Funcionalidade da lâmina de espinhos
Agora você precisa adicionar a funcionalidade real para a lâmina de espinhos. Remova a linha de código que registra o evento de ataque, pois você não precisa mais disso. Seu código deve ser semelhante ao seguinte. Sinta-se à vontade para copiar e colar, pois também contém alguns comentários de código úteis.
| ItemThornsBlade.cs |
usando Vintagestory.API.Common;
usando Vintagestory.API.Common.Entities;
namespace VSTutorial.Items
{
/*
* Como se trata de um item, você precisa herdar a classe Item. Isso dá acesso a funções em Item e CollectibleObject.
* Dê uma olhada em https://apidocs.vintagestory.at/api/Vintagestory.API.Common.Item.html#methods e
* https://apidocs.vintagestory.at/api/Vintagestory.API.Common.CollectibleObject.html#methods para todos os métodos que podem ser substituídos.
*/
classe interna ItemThornsBlade: Item
{
/*
* Esta função é chamada sempre que este item é utilizado por uma entidade para atacar outra entidade.
* Você tem acesso ao mundo, à entidade que está atacando, à entidade que está sendo atacada e aos dados do item retido.
*/
substituição pública void OnAttackingWith (IWorldAccessor world, Entity byEntity, Entity attackEntity, ItemSlot itemslot)
{
base.OnAttackingWith(mundo, byEntity, attackEntity, itemslot);
}
<div lang="en" dir="ltr" class="mw-content-ltr">
}
}
</div>
|
Observe que qualquer código adicional nesta função pode ser colocado acima ou abaixo da chamada 'base'. Neste caso, a ordem não importa.
Refletindo Dano
Para infligir danos a uma entidade, existem dois pequenos passos:
- Uma instância DamageSource deve ser criada.
- A fonte do dano deve ser infligida à entidade usando a função Entity.ReceiveDamage.
Antes de poder infligir dano a uma entidade, você deve criar uma fonte de dano. Isso inclui o tipo de dano e pode conter informações sobre a origem do dano. Observe que ele não contém a quantidade de dano.
DamageSource damage = new DamageSource()
{
Type = EnumDamageType.PiercingAttack,
SourceEntity = byEntity,
KnockbackStrength = 0
};
Isso cria uma nova instância de fonte de dano chamada 'dano'. O tipo pode ser qualquer instância de EnumDamageType, mas para esse propósito você deve usar PiercingAttack. CauseEntity é a entidade que causou o dano, que deve ser qualquer coisa que esteja usando nossa espada.
Agora que a fonte de dano foi criada, você precisa infligir isso à entidade. A entidade que usou o item é 'byEntity', então você vai querer danificá-los:
byEntity.ReceiveDamage(damage, 0.25f);
Isso infligirá 0,25 pontos de dano à entidade, usando nossa instância de ‘dano’ que acabamos de criar. E é isso. Quando o item for usado para atacar, 0,25 pontos de dano serão infligidos ao jogador que estiver usando a arma.
O código completo deve ser o seguinte:
| ItemThornsBlade.cs |
usando Vintagestory.API.Common;
usando Vintagestory.API.Common.Entities;
namespace VSTutorial.Items
{
/*
* Como se trata de um item, você precisa herdar a classe Item. Isso dá acesso a funções em Item e CollectibleObject.
* Dê uma olhada em https://apidocs.vintagestory.at/api/Vintagestory.API.Common.Item.html#methods e
* https://apidocs.vintagestory.at/api/Vintagestory.API.Common.CollectibleObject.html#methods para todos os métodos que podem ser substituídos.
*/
classe interna ItemThornsBlade: Item
{
/*
* Esta função é chamada sempre que este item é utilizado por uma entidade para atacar outra entidade.
* Você tem acesso ao mundo, à entidade que está atacando, à entidade que está sendo atacada e aos dados do item retido.
*/
substituição pública void OnAttackingWith (IWorldAccessor world, Entity byEntity, Entity attackEntity, ItemSlot itemslot)
{
Dano de Fonte de Dano = novo Fonte de Dano()
{
Tipo = EnumDamageType.PiercingAttack,
FonteEntidade = porEntidade,
Força de empurrão = 0
};
byEntity.ReceiveDamage(dano, 0,25f);
base.OnAttackingWith(mundo, byEntity, attackEntity, itemslot);
}
<div lang="en" dir="ltr" class="mw-content-ltr">
}
}
</div>
|
Vá em frente e teste a nova espada. Você precisará estar no modo de sobrevivência, mas descobrirá que atingir uma entidade também causará danos a si mesmo.
Conclusão
Parabéns, você criou, registrou e testou uma nova classe de item!
Próximas etapas...
Se você quiser testar seus conhecimentos, considere realizar as tarefas da seção “Indo além” abaixo.
Quando estiver pronto, dê uma olhada no próximo tutorial. Isso mostrará como registrar e adicionar comandos ao jogo!
Indo além
Quer fazer algumas alterações adicionais neste mod? Tente e consiga as seguintes coisas!
Atualmente, a espada irá causar danos a você mesmo se for usada em mobs que estão mortos. Faça com que ele cause dano apenas se a entidade atacada estiver viva.
| Para conseguir isso... |
Verifique se o campo 'Alive' em 'attackedEntity' é verdadeiro antes de infligir dano.if (attackedEntity.Alive)
{
byEntity.ReceiveDamage(damage, 0.25f);
}
|
Usando a função reviver na classe Entidade, faça a espada reviver quaisquer entidades mortas atingidas por ela.
| Para conseguir isso... |
Verifique se o campo 'alive' é falso e, em seguida, chame a função Revive em 'attackedEntity'.if (!attackedEntity.Alive)
{
attackedEntity.Revive();
}
|
