Vetores relativos do Elite Script

Para que servem

Os vetores relativos são definidos em relação a uma posição específica, mas dinâmica.

Por exemplo, para puxar um jogador para um boss em movimento, calcula um vetor da posição do jogador até à posição do boss. Um vetor fixo não acompanha as mudanças de posição.

Os vetores relativos permitem apontar projéteis, lançar blocos em queda e definir orientações. Como deslocamentos relativos, podem posicionar um reforço para lá de um jogador ou prolongar um raio além do alvo.

Contexto de utilização

Nas ações, usa-se a chave YAML RelativeVector:. As ações abrangidas são:

• SUMMON_ENTITY: define a velocidade, incluindo direção e intensidade, da entidade criada.
• SUMMON_REINFORCEMENT: define a velocidade do reforço criado.
• SPAWN_PARTICLE: fornece o vetor de movimento dentro de cada entrada de particles:; o campo ao nível da ação não é usado para este fim.
• PUSH: define a velocidade do empurrão.
• SPAWN_FALLING_BLOCK: define a velocidade do bloco em queda.
• SET_FACING: define a direção para a qual uma entidade olha.

As restantes ações interpretam um bloco RelativeVector: válido, mas não o usam. Estas chaves não distinguem maiúsculas de minúsculas: as entradas de partículas aceitam RelativeVector: e relativeVector:. Os valores dos tipos de alvo mantêm as maiúsculas documentadas.

Nas ações de velocidade, RelativeVector tem prioridade sobre vValue; os dois não são somados. PUSH calcula um único vetor para todas as entidades selecionadas e aplica-o um tick depois. SET_FACING também calcula uma única direção para todas as entidades selecionadas.

Para alterar posições de alvos, coloca relativeOffset: num bloco de alvo como Target, FinalTarget, Target2 ou FinalTarget2. Um relativeOffset: ao nível da ação regista Failed to read key relativeOffset .... Só produz efeito quando a ação não tem bloco Target, porque o alvo predefinido SELF lê então as chaves de alvo da própria ação. Consulta a secção de deslocamentos relativos abaixo.

Como funcionam os vetores?

Podes imaginar um vetor como uma seta que aponta de um ponto para outro.

Uma das suas propriedades é o comprimento. Numa flecha disparada, representa a velocidade; num deslocamento de posição, representa a distância. Pontos mais afastados produzem vetores mais compridos.

Quando só precisas da direção, podes normalizar o vetor: a direção é preservada e o comprimento passa a 1.0. Depois, um multiplicador permite ajustar o deslocamento ou a velocidade desejada.

Propriedades

Valor	Detalhes	Obrigatório?	Valor predefinido
SourceTarget	Alvo no ponto de origem do vetor	✅	none
DestinationTarget	Alvo no ponto de destino do vetor	✅	none
normalize	Define se o vetor é normalizado	❌	false
multiplier	Multiplica o comprimento. Aceita intervalos com ~, por exemplo 1.0~2.5.	❌	1.0
offset	Acrescenta um deslocamento fixo. Aceita intervalos com ~, por exemplo 0~5,0~2,0~10.	❌	0,0,0

Aleatoriedade

Tanto multiplier como offset aceitam intervalos delimitados por til (~):

• multiplier: usa min~max, por exemplo 1.0~2.5. Este exemplo produz valores desde 1.0 até 2.5, sem incluir 2.5.
• offset: usa x1~x2,y1~y2,z1~z2, por exemplo 0~5,0~2,0~10. Cada componente X, Y e Z é sorteada de forma independente.

Os valores são sorteados sempre que o vetor é calculado. As componentes aleatórias do deslocamento usam a mesma regra: de min até max, sem incluir max.

Exemplo

eliteScript:
  ShootChicken:
    Events:
    - EliteMobDamagedByPlayerEvent
    Actions:
    - action: SUMMON_ENTITY
      sValue: CHICKEN
      Target:
        targetType: SELF
      RelativeVector:
        SourceTarget:
          targetType: SELF
        DestinationTarget:
          targetType: DIRECT_TARGET
        normalize: true
        multiplier: 2.0

Lança uma galinha do boss em direção ao jogador atacante.

---

eliteScript:
  ShootArrow:
    Events:
    - EliteMobDamagedByPlayerEvent
    Actions:
    - action: SUMMON_ENTITY
      sValue: ARROW
      Target:
        targetType: SELF
      RelativeVector:
        SourceTarget:
          targetType: SELF
        DestinationTarget:
          targetType: DIRECT_TARGET
        normalize: true
        multiplier: 2.0

Dispara uma flecha para o jogador atacante. Para entidades projétil com um boss vivo, SUMMON_ENTITY usa o lançador de projéteis do boss; o projétil parte, por isso, do boss mesmo que o Target da ação indique outra posição.

---

eliteScript:
  SpawnReinforcement:
    Events:
    - EliteMobDamagedByPlayerEvent
    Actions:
    - action: SUMMON_ENTITY
      sValue: ZOMBIE
      Target:
        targetType: DIRECT_TARGET
        relativeOffset:
          SourceTarget:
            targetType: SELF
          DestinationTarget:
            targetType: DIRECT_TARGET
          normalize: true
          multiplier: 2.0

Cria um zombie vanilla dois blocos além do jogador, seguindo a linha do boss ao jogador. Apesar do nome do script, não é um reforço EliteMobs. relativeOffset pertence dentro de Target: altera a posição de aparecimento, não a velocidade. A direção usa a linha tridimensional completa, não a orientação do jogador, e este deslocamento não procura solo nem verifica colisões.

---

eliteScript:
  Example:
    Events:
    - EliteMobDamagedByPlayerEvent
    Zone:
      Shape: SPHERE
      target:
        targetType: SELF_SPAWN
        offset: 0,0,0
        track: false
      filter: PLAYER
      radius: 6
    Actions:
    - action: SPAWN_PARTICLE
      repeatEvery: 38
      times: 5
      Target:
        targetType: ZONE_FULL
        track: false
        coverage: 0.9
      particles:
      - particle: FLAME
        RelativeVector:
          SourceTarget:
            targetType: ACTION_TARGET
            track: true
          DestinationTarget:
            targetType: SELF_SPAWN
            offset: 0,-0.5,0
        speed: 0.05

Cria rajadas repetidas de chamas que se movem para dentro de uma esfera em torno da posição de aparecimento. A zona em si não encolhe.

Como funciona:

• A zona fornece pontos geométricos dentro de uma esfera de seis blocos. filter: PLAYER afeta a seleção de entidades, não as posições das partículas usadas aqui.
• coverage: 0.9 dá a cada ponto gerado cerca de 90 % de probabilidade de ser selecionado. O track: false da ação guarda essa seleção para as repetições desta execução.
• O vetor de cada partícula aponta da sua posição de aparecimento (ACTION_TARGET) para meio bloco abaixo da posição de aparecimento do boss (SELF_SPAWN com offset: 0,-0.5,0).
• O vetor é calculado ao criar cada partícula. ACTION_TARGET usa diretamente a posição fornecida pela ação; o seu track aninhado não orienta partículas já em movimento.
• Um vetor relativo de partículas substitui x, y, z e força amount a zero para emissão direcional. speed continua a ser passado ao Bukkit e o tipo de partícula determina o movimento resultante.
• A ação executa-se cinco vezes, com 38 ticks de intervalo, salvo cancelamento do trabalho agendado. Cada golpe válido inicia outra execução porque este exemplo não tem tempo de recarga.

Ordem das operações

As propriedades são aplicadas nesta ordem:

Cálculo do vetor -> normalize -> multiplier -> offset

Notas técnicas

Normalização: Num vetor não nulo, preserva a direção e define o comprimento como 1.0 antes do multiplicador e do deslocamento.

Multiplicadores negativos: Um multiplicador negativo inverte a direção. Por exemplo, -1.0 aponta no sentido oposto.

Coordenadas do deslocamento: O deslocamento usa os eixos do mundo, não os da direção do vetor. É somado depois dos outros cálculos.

Validação do mundo: Os alvos de origem e destino têm de estar no mesmo mundo. Caso contrário, é devolvido um vetor zero (0, 0, 0), o que pode fazer ações falharem ou produzirem resultados inesperados.

Alvos ausentes: Uma coleção resolvida de origem ou destino vazia devolve um vetor zero antes do multiplicador e do deslocamento. Isto inclui um extremo DIRECT_TARGET quando o evento não tem alvo direto. Um bloco SourceTarget ou DestinationTarget em falta continua a causar um erro.

Se as posições válidas de origem e destino coincidirem, o vetor tem comprimento zero. normalize: true mantém-no a zero, pelo que só resta o offset do próprio vetor relativo. Quando um alvo resolve várias posições, o vetor relativo usa a primeira, sem garantir a mais próxima. Usa um alvo único como DIRECT_TARGET quando a direção tiver de ser inequívoca.

ACTION_TARGET: Usa uma posição fornecida pela ação e ignora os parâmetros de alvo aninhados offset, relativeOffset e track. Para partículas, é a posição da partícula; para entidades e blocos em queda, a posição pedida; para a velocidade de reforços, a posição do reforço criado. Para PUSH e SET_FACING, é a posição do boss, não de cada entidade selecionada. No relativeOffset de um alvo, é a posição que está a ser deslocada, depois do offset simples desse alvo.

Velocidade e posição: Numa ação como SUMMON_ENTITY, RelativeVector define a velocidade da entidade. Num alvo, relativeOffset define um deslocamento de posição. O cálculo subjacente é o mesmo, mas a interpretação depende do contexto.

Aplica relativeOffset a alvos como SELF, SELF_SPAWN, DIRECT_TARGET, LOCATION ou LOCATIONS, incluindo quando definem a origem ou o extremo de uma zona. Em ZONE_FULL / ZONE_BORDER, desloca cada localização amostrada da zona. Não tem efeito em LANDING_LOCATION nem em INHERIT_SCRIPT_TARGET. Consulta as regras dos deslocamentos de alvo.

Deslocamento relativo do Elite Script

Para que servem?

Os deslocamentos relativos funcionam de forma semelhante aos vetores relativos, permitindo ajustar dinamicamente as posições dos alvos ou efeitos conforme o contexto.

Como funcionam os deslocamentos relativos?

São aditivos: o resultado é somado ao valor base, como uma posição ou vetor.

Considera uma zona em raio:

• Target 1 é SELF, o boss.
• Target 2 é DIRECT_TARGET, o jogador fornecido pelo evento.

Supõe que o jogador está a oito blocos, ambas as posições pertencem ao mesmo mundo e não há outros deslocamentos. Usa SELF como SourceTarget do deslocamento relativo e DIRECT_TARGET como DestinationTarget, e coloca esse relativeOffset em Target2. Estes exemplos descrevem a distância ao extremo; os pontos desenhados também dependem dos parâmetros do raio.

Aplica agora o deslocamento relativo:

Caso 1: normalize = false, multiplier = 1

• A distância original é 8.
• O deslocamento vale 8 × 1 = 8.
• O comprimento final é 8 + 8 = 16.

O raio atravessa o jogador e continua por mais oito blocos.

Caso 2: normalize = false, multiplier = 2

• O deslocamento vale 8 × 2 = 16.
• O comprimento final é 8 + 16 = 24.

Caso 3: normalize = true, multiplier = 1

• A distância é normalizada para 1.
• O deslocamento vale 1 × 1 = 1.
• O comprimento final é 8 + 1 = 9.

Caso 4: normalize = true, multiplier = 2

• O deslocamento vale 1 × 2 = 2.
• O comprimento final é 8 + 2 = 10.

Resumo

• normalize = false usa a distância real entre os alvos.
• normalize = true parte de comprimento 1 num vetor válido não nulo.
• O deslocamento é sempre somado ao valor original.
• Um multiplier de zero remove o deslocamento calculado apenas se este for finito. O offset do próprio vetor relativo continua a ser somado depois, e o offset normal do alvo permanece separado. Para desativar o deslocamento relativo, remove o seu bloco.

Este sistema permite prolongar ou encurtar distâncias dinamicamente nos scripts EliteMobs.

Propriedades

Valor	Detalhes	Obrigatório?	Valor predefinido
SourceTarget	Alvo no ponto de origem do vetor	✅	none
DestinationTarget	Alvo no ponto de destino do vetor	✅	none
normalize	Define se o vetor é normalizado	❌	false
multiplier	Multiplica o comprimento. Aceita intervalos com ~, por exemplo 1.0~2.5.	❌	1.0
offset	Soma um vetor fixo após normalize e multiplier. Aceita intervalos com ~, por exemplo 0~5,0~2,0~10.	❌	0,0,0

relativeOffset e RelativeVector são interpretados pelo mesmo código e aceitam as mesmas cinco chaves.

Exemplo

eliteScript:
  MakeStaticRay:
    Events:
    - EliteMobDamagedByPlayerEvent
    Zone:
      shape: STATIC_RAY
      Target:
        targetType: SELF
        offset: 0,1,0
      Target2:
        targetType: DIRECT_TARGET
        offset: 0,1,0
        relativeOffset:
          sourceTarget:
            targetType: SELF
          destinationTarget:
            targetType: DIRECT_TARGET
          multiplier: 5
          normalize: true
    Actions:
    - action: SPAWN_PARTICLE
      Target:
        targetType: ZONE_FULL
      particles:
      - particle: ELECTRIC_SPARK
        amount: 1
      repeatEvery: 1
      times: 400

O extremo deste raio fica cinco blocos além do jogador, seguindo a linha do boss ao jogador. Os deslocamentos normais elevam ambos os extremos um bloco acima dos pés; não calculam automaticamente o centro das entidades. STATIC_RAY designa a forma, não uma captura fixa dos alvos: com o track: true predefinido, a ação recalcula os alvos nas repetições. Define Target.track: false na ação para guardar as posições geradas do raio e obter uma apresentação fixa. O exemplo pede 400 execuções com um tick de intervalo; cada golpe válido pode iniciar outra série.

Nota: O exemplo aplica um deslocamento relativo a uma zona, mas estes deslocamentos também podem ser aplicados a outros alvos.